Indice

Flow-e Connect

Ordini, resi e profilo cliente

Collegare l'API ordini del negozio: stato dell'ordine in chat, resi e cambi, profilo dei clienti con login.

Aggiornato il 15 novembre 2026Versione 1.2Negozi su piattaforma propria

Introduzione

Flow-e legge gli ordini di un singolo cliente, al momento della richiesta, dal sistema del negozio. Il collegamento (adattatore) è a cura di Flow-e. Al negozio è richiesto un accesso in sola lettura a un'API ordini: un'API esistente è utilizzabile nel suo formato; per un nuovo endpoint il formato consigliato è Flow-e Orders API v1.
  1. 1PanoramicaLe funzioni disponibili al cliente in chat: ordini, resi, profilo.
  2. 2Le strade possibiliAPI esistente in qualunque formato, nuovo endpoint nel formato consigliato, oppure rimando alla pagina ordini.
  3. 3Requisiti dell'endpointDue ricerche, sola lettura, https, risposta entro 4 secondi.

Panoramica: cosa vede il cliente in chat#

FunzioneComportamento in chatRequisito
Stato dell'ordine, cliente ospiteAlla richiesta del cliente («dov'è il mio ordine?») l'assistente chiede numero d'ordine ed email e presenta la scheda dell'ordine: stato, data, importi, articoli, corriere con numero e link di tracciamento, link alla pagina dell'ordine sul sito.ricerca search (numero d'ordine + email)
Stato dell'ordine, cliente con loginAlla richiesta «i miei ordini» l'assistente presenta gli ultimi ordini (fino a 5 in elenco, oppure l'ordine in corso) senza richiedere numero o email.ricerca by_customer (codice cliente) e firma del cliente
Resi e cambiDalla scheda dell'ordine il cliente apre il pannello del reso, con i soli articoli ancora rendibili; indica motivo e soluzione (rimborso, cambio con altra variante, sostituzione, riparazione) e allega foto se richieste. La richiesta è registrata come ticket nel portale Flow-e del negozio e, se configurato, inviata al sistema del negozio con l'evento return.requested.gli stessi dati dello stato ordine, con le righe; regole definite dal negozio nel portale
Profilo clientePer i clienti con login Flow-e ricava dagli ultimi ordini un riepilogo (categorie e marche più acquistate, spesa media, acquisti in promozione, taglie per categoria), utilizzato per suggerimenti più pertinenti.ricerca by_customer e firma del cliente

Se il sistema del negozio non risponde, l'assistente segnala un problema tecnico e non fornisce dati non verificati; se gli errori si ripetono, Flow-e sospende per breve tempo le chiamate verso l'API del negozio (protezione dell'API). Un ordine inesistente e un'email errata ricevono la stessa risposta: la risposta non rivela l'esistenza di un numero d'ordine, e i tentativi da ospite sono limitati (limite ai tentativi).

Le strade possibili#

Strada A — API ordini esistente, in qualunque formato#

L'API non richiede modifiche: la conversione nel formato Flow-e è eseguita dall'adattatore. Per il collegamento sono necessari:

  1. La documentazione dell'API (link o PDF) e l'indirizzo dell'ambiente di prova, se disponibile.
  2. Una chiave di sola lettura dedicata a Flow-e e limitata agli ordini, trasmessa su un canale sicuro (non per email in chiaro). La chiave è conservata esclusivamente nel gestore delle credenziali di Flow-e.
  3. Due ordini di prova con le email associate, preferibilmente di clienti di prova, uno spedito e uno consegnato, e un codice cliente di prova con almeno due ordini.
  4. L'elenco degli stati d'ordine del sistema, con il significato di ciascuno.
  5. I campi facoltativi disponibili: opzioni della variante (taglia, colore), categoria e marca delle righe, quantità ancora rendibile, date di spedizione e consegna.
  6. L'autorizzazione dell'IP di Flow-e, se l'API è protetta per indirizzo.

Esempio di corrispondenza tra campi (API ipotetica, a solo titolo illustrativo):

Campo dell'API del negozioCampo Flow-e
orderNumberorder_ref
createdAtplaced_at
state: "SENT"status: "shipped"
buyer.email · buyer.idemail · customer_ref
lines[].qtyOrdereditems[].qty

Strada B — nessuna API ordini: formato consigliato «Flow-e Orders API v1»#

Per un nuovo endpoint il formato consigliato è Flow-e Orders API v1 (riferimento API): richiesta e risposta coincidono con il formato utilizzato da Flow-e e non richiedono conversione. L'endpoint è in sola lettura e prevede due ricerche. In alternativa è possibile concordare la lettura da un altro sistema che già contiene gli ordini (gestionale, ERP).

Invio degli ordini e assistente

L'invio degli ordini con POST /api/connect/v1/orders (vedere il riferimento OpenAPI) serve esclusivamente all'attribuzione delle visite alle vendite: non alimenta lo stato dell'ordine, i resi né il profilo.

Strada C — rimando alla pagina «I miei ordini»#

Nessun dato d'ordine transita da Flow-e. Alle richieste su ordini o resi l'assistente risponde con le indicazioni e i collegamenti inseriti dal negozio nella propria base di conoscenza (per esempio la pagina «I miei ordini» e la pagina dei resi).

Requisiti minimi dell'endpoint#

I requisiti valgono per qualunque formato (strada A o B).

TemaRequisito
Due ricercheper numero d'ordine (ospiti): l'ordine con quel numero, comprensivo dell'email del cliente. Per codice cliente (clienti con login): gli ordini del cliente, fino a 25, preferibilmente in ordine decrescente di data, ciascuno comprensivo del codice cliente
Email e codice clienteutilizzati esclusivamente per la verifica di proprietà e rimossi subito dopo: non sono mostrati in chat né conservati
Protocolloesclusivamente https://, con certificato valido
Autenticazionechiave in un'intestazione HTTP (Authorization: Bearer … oppure X-Api-Key: …), mai nell'indirizzo
Tempo di rispostaentro 4 secondi; oltre tale limite la chiamata è considerata non riuscita
Dimensione della rispostacorpo fino a 1 MB; una risposta più grande è considerata non riuscita
Intestazione X-Request-Idpresente in ogni chiamata di Flow-e: identificativo univoco della chiamata, da registrare nei log del negozio per correlare le chiamate
Permessisola lettura, limitata agli ordini
Ordine non trovato200 con elenco vuoto, oppure 404
Errori401/403, 429, 5xx, corpo non JSON: «sistema non disponibile»
FormatiJSON UTF-8; date ISO 8601 con fuso orario (2026-11-02T10:15:00Z); importi come numeri o stringhe con il punto decimale
Identificativiqualunque stringa (anche C-00A93F), confrontata per uguaglianza esatta e mai ridotta a cifre; fino a 128 caratteri; il numero d'ordine segue le regole della richiesta
Volumeuna chiamata per ogni richiesta del cliente; per il profilo al massimo una chiamata all'ora per cliente con login; con la protezione dell'API

Dati esclusi

Indirizzi, numeri di telefono, dati di pagamento e note interne non sono richiesti. Se l'API li restituisce, l'adattatore li scarta: non sono copiati né conservati.

Richiesta#

Un unico indirizzo, metodo POST, corpo JSON, chiave nell'intestazione. Due operazioni:

CampoTipoQuandoSignificato
operation"search" | "by_customer"semprericerca da ospite o del cliente con login
order_refstring ≤ 64searchnumero d'ordine come indicato al cliente, senza #
emailstring ≤ 254searchemail indicata dal cliente, confrontata da Flow-e con quella dell'ordine
customer_refstring ≤ 128by_customercodice cliente, identico a quello della firma
limitinteger 1-25by_customernumero massimo di ordini, in ordine decrescente di data

Intestazioni di ogni chiamata: Content-Type: application/json, la chiave di sola lettura e X-Request-Id (identificativo univoco della chiamata, da registrare nei log del negozio).

Numero d'ordine#

La ricerca da ospite è garantita su tutti i canali per i numeri d'ordine che rispettano le regole seguenti. Il pannello dei resi del widget le applica al numero indicato dal cliente; la chat accetta fino a 64 caratteri senza spazi.

RegolaDettaglio
Lunghezzada 1 a 64 caratteri
Caratteri ammessilettere ASCII (A-Z, a-z), cifre (0-9) e i simboli - _ . /
Primo carattereuna lettera, una cifra oppure -
Sequenze escluse.. e //
# inizialetolto prima della chiamata: #SP-1001 diventa SP-1001

Campi della risposta#

Radice: { "orders": [ … ] }, al massimo 25 ordini. Gli identificativi sono sempre stringhe (un valore numerico viene convertito). I campi non previsti sono ignorati.

CampoTipoObbligatorioUtilizzo
order_refstring ≤ 64sìnumero d'ordine visibile al cliente: ricerca e scheda
order_idstring ≤ 128 | nullnoidentificativo interno; riferimento nei resi
placed_atstring ISO 8601sìscheda, ordinamento, profilo
statusenum (9 valori)sìscheda
status_labelstring | nullnoetichetta nella lingua del negozio, mostrata quando lo stato è unknown
closedbooleanconsigliatotrue = ordine non più rendibile (annullato, pagamento annullato, rimborsato)
currencystring ISO 4217sìscheda, profilo
totals.totalnumbersìscheda, profilo
totals.subtotal · shipping · discount · taxnumber | nullnoscheda; discount alimenta il profilo (acquisti in promozione)
emailstringsìverifica del cliente ospite
customer_refstring ≤ 128sì per i clienti con loginverifica del cliente con login
order_page_urlhttps | nullnopulsante nella scheda
shipments[]array ≤ 10consigliatoscheda; il termine del reso decorre dalla consegna (o dalla spedizione + 7 giorni)
shipments[].carrier · tracking_number · tracking_urlstring | nullnocorriere e tracciamento
shipments[].shipped_at · eta · delivered_atstring ISO 8601 | nullconsigliatospedizione, consegna prevista, consegna
items[]array ≤ 50sìrighe dell'ordine
items[].line_refstring ≤ 128consigliato (sì per i resi)identifica l'articolo da rendere
items[].sku · product_refstring | nullconsigliatoidentici a quelli del catalogo Flow-e: immagini, cambi con altre varianti, esclusioni dal reso
items[].namestringsìscheda
items[].variantstring | nullnoetichetta della variante (M · Blue)
items[].options[][{ name, value }] ≤ 10noopzioni della variante (Size: M): profilo, taglie per categoria
items[].qtynumbersìquantità ordinata
items[].qty_returnablenumber | nullconsigliatoquantità ancora rendibile (in assenza vale qty)
items[].unit_price_paid · unit_price_listnumber | nullnoscheda, articoli in saldo nei resi
items[].image_urlhttps | nullnoscheda
items[].brand · categorystring | nullnoprofilo; esclusioni dal reso per marca o categoria
items[].tags[]string[] ≤ 20noesclusioni dal reso per etichetta

Limiti applicati alla risposta#

Il corpo è accettato fino a 1 MB; oltre, la risposta è considerata non riuscita. Entro quel limite valgono le regole seguenti e la risposta resta valida.

ElementoLimiteOltre il limite
Ordini25gli ordini in eccesso sono ignorati
Righe per ordine (items[])50le righe in eccesso sono ignorate
Spedizioni per ordine (shipments[])10le spedizioni in eccesso sono ignorate
Opzioni per riga (items[].options[])10le opzioni in eccesso sono ignorate
Etichette per riga (items[].tags[])20le etichette in eccesso sono ignorate
items[].name, items[].brand, items[].category200 caratteritesto troncato
items[].variant, nome e valore di items[].options[], items[].tags[]120 caratteritesto troncato
Altri testi500 caratteritesto troncato
order_ref64 caratteril'intero ordine è scartato
Altri identificativi (order_id, customer_ref, line_ref, sku, product_ref)128 caratterivalore ignorato, mai troncato
email254 caratterivalore ignorato
Indirizzi (order_page_url, tracking_url, image_url)solo https://, fino a 2000 caratteri, senza spazi, virgolette né parentesi angolarivalore ignorato

Un identificativo non è mai troncato: un valore troncato potrebbe coincidere con quello di un altro ordine o di un altro cliente. Un oggetto o un array al posto di un testo è ignorato.

Stati dell'ordine#

Nella strada A ogni stato del sistema del negozio è associato a uno dei nove valori seguenti. Un valore non previsto diventa unknown e la scheda mostra status_label.

statusSignificato
pending_paymentin attesa di pagamento
processingpagato, in lavorazione
shippedspedito
partially_shippedspedito in parte
deliveredconsegnato
cancelledannullato
refundedrimborsato
returnedreso
unknownnon riconosciuto (viene mostrato status_label)

Esempi#

Richiesta#

bash
# search — guest (order number + email)
curl -X POST https://api.store.example/flowe/orders \
  -H "X-Api-Key: <read-only key>" \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: 348112" \
  -d '{"operation":"search","order_ref":"SP-1001","email":"mario.rossi@connect.test"}'
bash
# by_customer — logged-in customer, up to 25 orders
curl -X POST https://api.store.example/flowe/orders \
  -H "X-Api-Key: <read-only key>" \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: 348113" \
  -d '{"operation":"by_customer","customer_ref":"C-0093","limit":25}'

Risposta (dati fittizi)#

json
{
  "orders": [{
    "order_ref": "SP-1001",
    "order_id": "9001",
    "placed_at": "2026-11-02T10:15:00Z",
    "status": "shipped",
    "status_label": "Shipped",
    "closed": false,
    "currency": "EUR",
    "totals": { "total": 177.9, "subtotal": 171, "shipping": 6.9, "discount": 0, "tax": null },
    "email": "mario.rossi@connect.test",
    "customer_ref": "C-0093",
    "order_page_url": "https://shop.example.com/account/orders/SP-1001",
    "shipments": [{
      "carrier": "BRT",
      "tracking_number": "BRT000123456",
      "tracking_url": "https://www.brt.it/it/tracking",
      "shipped_at": "2026-11-03T08:00:00Z",
      "eta": "2026-11-06T00:00:00Z",
      "delivered_at": null
    }],
    "items": [{
      "line_ref": "1",
      "sku": "MG-JACKET-M-BLU",
      "product_ref": "MG-JACKET",
      "name": "Softshell jacket",
      "variant": "M · Blue",
      "options": [{ "name": "Size", "value": "M" }, { "name": "Colour", "value": "Blue" }],
      "qty": 1,
      "qty_returnable": 1,
      "unit_price_paid": 119.9,
      "unit_price_list": 129.9,
      "image_url": "https://shop.example.com/media/mg-jacket.jpg",
      "brand": "Montagna",
      "category": "Jackets",
      "tags": ["outdoor"]
    }]
  }]
}

Ordine non trovato#

http
HTTP/1.1 200 OK
Content-Type: application/json

{ "orders": [] }

In alternativa 404. La risposta è identica per un numero inesistente e per un'email errata.

Indirizzo IP da autorizzare#

Le chiamate verso l'API del negozio provengono da un unico server Flow-e con indirizzo IP fisso. Se l'API è protetta da firewall o da un elenco di indirizzi ammessi, va autorizzato il seguente IP: 72.60.81.115 (IPv4). Un eventuale cambio di indirizzo è comunicato per iscritto prima della sua entrata in vigore.

In presenza di una protezione anti-bot (WAF, Cloudflare, Fastly), l'indirizzo dell'API va escluso dalla verifica.

Clienti con login: codice cliente nella firma e negli ordini#

Per il riconoscimento di un cliente con login, la pagina del negozio trasmette allo script Flow-e il codice cliente firmato dal server del negozio. Lo snippet per i siti su piattaforma propria è disponibile nel portale Flow-e in Integrazioni › Installa il widget (embed-v2.js); per il cliente con login si aggiungono gli attributi d'identità:

html
<script src="https://<widget>/embed-v2.js"
  data-widget-url="https://<widget>"
  data-api-key="pk_live_…"
  data-user-id="C-0093"
  data-user-ts="1763116800"
  data-user-hmac="<signature>"
  data-logged-in="true" defer></script>

La firma è calcolata sul server, mai nel browser:

text
signature = HMAC-SHA256( secret, "<customer_ref>:<ts>" )   // lowercase hex
ts        = Unix seconds when the page is generated
php
<?php
// Server side: the secret never reaches the browser
$ts        = (string) time();
$signature = hash_hmac('sha256', $customerRef . ':' . $ts, $secret);
javascript
// Node.js, server side
import { createHmac } from "node:crypto";
const ts = String(Math.floor(Date.now() / 1000));
const signature = createHmac("sha256", secret).update(`${customerRef}:${ts}`).digest("hex");
RegolaDettaglio
Segretola Identity Secret Key dell'organizzazione, nel portale Flow-e in Integrazioni › Chiavi API. Resta sul server: mai nella pagina né nel codice JavaScript
Validità24 ore dal ts; un ts successivo all'ora corrente di oltre 5 minuti è rifiutato
data-user-ididentico al valore che l'API del negozio restituisce come customer_ref, carattere per carattere (1-128 caratteri, senza spazi né caratteri di controllo)
Cliente senza loginesclusivamente data-logged-in="false", senza altri attributi d'identità

Corrispondenza del codice cliente

Se la firma usa l'identificativo numerico interno e l'API ordini restituisce un codice diverso (per esempio C-0093), la verifica non riesce e il cliente non vede i propri ordini. I codici non sono mai ridotti a cifre: C-0093 e 0093 sono clienti distinti.

Sicurezza e privacy#

Verifica di proprietà#

L'adattatore interroga l'API e converte la risposta; non stabilisce quali ordini il cliente può vedere. Dopo ogni risposta, un controllo nel codice di Flow-e (non un modello di intelligenza artificiale) mantiene esclusivamente gli ordini del cliente:

  • ospite: un ordine è mostrato solo se order_ref ed email coincidono con quelli indicati dal cliente. Se l'API non restituisce l'email, all'ospite non è mostrato alcun ordine; mai un elenco, al massimo un ordine;
  • cliente con login: solo gli ordini il cui customer_ref coincide con quello della firma verificata;
  • gli ordini di altri clienti eventualmente restituiti dall'API sono scartati;
  • email e customer_ref sono quindi rimossi da ogni ordine;
  • customer_ref deve essere una stringa (o un numero): un array o un oggetto non supera la verifica.

Su richiesta del negozio la ricerca da ospite può essere disattivata (solo clienti con login); l'impostazione è gestita da Flow-e. In tal caso, alla richiesta di un ordine o di un reso, l'assistente invita il cliente ad accedere al proprio account sul sito.

Limite ai tentativi da ospite#

Dopo 5 ricerche senza esito (ordine non trovato o email non corrispondente) in 15 minuti per la stessa email o per lo stesso numero d'ordine, per i 15 minuti successivi le ricerche con quell'email o con quel numero ricevono la risposta «ordine non trovato», anche se i dati sono corretti. I problemi tecnici dell'API non contano come tentativi. Il limite impedisce di usare la ricerca per indovinare numeri d'ordine o email; email e numero sono confrontati senza distinzione tra maiuscole e minuscole, senza spazi iniziali o finali e senza i # iniziali.

Compromesso del limite. Chiunque conosca un'email o un numero d'ordine può, con 5 ricerche errate, bloccare per 15 minuti la ricerca da ospite di quell'email o di quel numero. Il cliente con login non è interessato: i suoi ordini sono letti con la firma del sito.

Dati conservati e durata#

DatoCollocazioneDurata
Risposta dell'API del negozionon conservata—
Ordine mostrato in chatnella conversazione, come ogni messaggio120 giorni
Profilo del cliente con login: riepilogo e ultimi ordini (fino a 25, con numero, data, totale, stato e articoli; senza email, codice cliente né indirizzi)profilo cliente Flow-e del negozioaggiornato al massimo una volta all'ora; cancellato dopo 120 giorni di inattività
Richiesta di resoticket del negozio nel portale Flow-ecome gli altri ticket del negozio
Contatori della protezione e del limite ai tentativi: per i tentativi da ospite soltanto l'impronta crittografica (SHA-256) di email e numero d'ordine, mai il testodatabase Flow-ecancellati entro 3 giorni dall'ultimo aggiornamento

Il profilo è creato esclusivamente per i clienti con login, con firma verificata, che visitano pagine con l'assistente, se il negozio ha attivato la personalizzazione e il cliente non vi si è opposto. Per i clienti ospiti non è creato alcun profilo. Flow-e non replica l'archivio ordini del negozio: legge soltanto gli ordini del cliente servito, al momento della richiesta.

Lato negozio#

  • Chiave dedicata a Flow-e, in sola lettura, revocabile in qualunque momento.
  • Ogni chiamata contiene soltanto i dati della ricerca (numero ed email, oppure codice cliente).
  • Ogni chiamata contiene l'intestazione X-Request-Id, identificativo univoco della chiamata, da registrare nei log del negozio per correlare le chiamate. Flow-e non conserva questi identificativi.
  • In caso di anomalia Flow-e comunica data e ora (UTC) e operazione interessata (search o by_customer); allo stesso modo, per segnalare una chiamata anomala, il negozio indica a Flow-e data e ora della chiamata.

Resi#

Una richiesta di reso inviata dal cliente è registrata come ticket della categoria «Resi» nel portale del negozio. Se il negozio ha configurato una destinazione webhook con l'evento return.requested, il sistema del negozio riceve la richiesta strutturata (righe, motivi, soluzioni, cambi, differenza di prezzo, termine), con firma HMAC-SHA256 secondo la specifica Standard Webhooks. Il contratto completo dell'evento sarà pubblicato nella sezione Webhook; nel frattempo è disponibile su richiesta.

Campo del webhookValore per i negozi collegati secondo questa guida
data.order.idorder_id dell'ordine, oppure order_ref in assenza di order_id
data.order.nameorder_ref, come indicato al cliente
data.order.platformla piattaforma del negozio
data.return.lines[].line_item_iditems[].line_ref restituito dall'API del negozio
data.return.lines[].exchange.variant_idl'identificativo del prodotto del catalogo Flow-e scelto per il cambio
data.return.customer_verified_byorder_email (ospite) o store_account (cliente con login)

Tutti gli identificativi sono stringhe opache fino a 128 caratteri, da conservare e confrontare senza trasformazioni. Flow-e non modifica l'ordine nel sistema del negozio: la gestione del reso resta in capo al negozio. Le regole del reso (termine, motivi ammessi, esclusioni, articoli in saldo, cambi) si definiscono nel portale Flow-e.

Collaudo#

Il collaudo si svolge sull'ambiente di prova, se disponibile, altrimenti sull'ambiente di produzione con dati di prova. Flow-e esegue i seguenti casi con gli ordini di prova forniti dal negozio:

#CasoEsito atteso
1ospite, numero ed email correttischeda dell'ordine
2ospite, email errata«ordine non trovato»
3ospite, numero inesistente«ordine non trovato», risposta identica al caso 2
4ospite, solo numero d'ordinel'assistente richiede l'email
5cliente con logini soli ordini del cliente
6cliente con login che indica il numero d'ordine di un altro cliente«ordine non trovato»
7API non raggiungibile o oltre 4 ssegnalazione di problema tecnico, nessun dato non verificato
8reso di un articolo consegnatopannello del reso e ticket creato; un secondo invio identico non crea un nuovo ticket
9reso di un ordine non spedito o annullatomotivazione, nessun reso
10API non raggiungibile per più chiamate consecutivedopo il quinto errore in 60 secondi le chiamate sono sospese per 60 secondi; nel frattempo segnalazione di problema tecnico; ripresa automatica
11ospite, 5 ricerche con email erratadopo la quinta richiesta non riuscita, «ordine non trovato» per 15 minuti anche con l'email corretta
12ricerca da ospite disattivatainvito ad accedere al proprio account

A collaudo superato Flow-e attiva il collegamento. La disattivazione è immediata e non interessa le altre funzioni dell'assistente.

Codici di risposta#

Risposta dell'API del negozioInterpretazione Flow-eRisposta al cliente
200 con uno o più ordinitrovato (segue la verifica di proprietà)la scheda, se l'ordine è del cliente
200 con { "orders": [] }, oppure 404non trovato«ordine non trovato»
401, 403chiave errata o revocata: sistema non disponibileproblema tecnico
429, 5xx, oltre 4 secondi, errore di rete, corpo non JSON o oltre 1 MBsistema non disponibileproblema tecnico

Nessun errore rivela al cliente l'esistenza di un ordine.

Protezione dell'API del negozio e allarmi#

SituazioneComportamento
5 risposte «sistema non disponibile» in 60 secondiFlow-e sospende le chiamate verso l'API di quel negozio per 60 secondi. Nell'intervallo l'assistente segnala subito il problema tecnico, con la possibilità di riprovare, senza interrogare l'API; al termine le chiamate riprendono automaticamente. La sospensione riguarda soltanto quel negozio.
Errori ripetutiavviso di tipo «errore dell'API» al team Flow-e, all'apertura della sospensione o dopo 3 errori in 30 minuti
L'API restituisce ordini di altri clientigli ordini sono scartati dalla verifica di proprietà e il team Flow-e riceve un avviso di tipo «ordini di altri clienti»: indica un difetto dell'endpoint
La risposta proviene da un collegamento configurato per un altro negoziola risposta è scartata, il cliente riceve la segnalazione di un problema tecnico e il team Flow-e riceve un avviso di tipo «isolamento» (controllo interno di Flow-e)
Frequenza degli avvisial massimo un avviso ogni 30 minuti per ciascun tipo; un tipo non trattiene gli avvisi degli altri

In caso di avviso il team Flow-e contatta il referente tecnico del negozio, indicando data e ora (UTC) e operazione delle chiamate interessate.

Domande frequenti#

Quali elementi sono necessari per il collegamento?#

Con un'API esistente: documentazione, chiave di sola lettura, ordini di prova e, se previsto, autorizzazione dell'IP di Flow-e. In assenza di un'API: un endpoint di sola lettura conforme ai requisiti. Per i clienti con login: la firma nella pagina.

Il formato Flow-e Orders API v1 è obbligatorio?#

No. Un'API esistente è utilizzabile in qualunque formato, con conversione a cura dell'adattatore. Il formato consigliato si applica ai nuovi endpoint, che in tal caso non richiedono conversione.

Il sistema del negozio deve inviare dati a Flow-e?#

No. È Flow-e a interrogare l'API del negozio, esclusivamente in risposta alla richiesta di un cliente.

Un errore dell'API può esporre ordini di altri clienti?#

No. La verifica di proprietà è eseguita da Flow-e e scarta ogni ordine non corrispondente.

Il codice cliente può essere alfanumerico?#

Sì: qualunque stringa fino a 128 caratteri, confrontata per uguaglianza esatta.

È possibile esporre la sola ricerca per numero d'ordine ed email?#

Sì: sono disponibili lo stato dell'ordine e i resi per i clienti ospiti. L'elenco degli ordini e il profilo dei clienti con login richiedono la ricerca per codice cliente.

Cosa accade se l'API è lenta o non disponibile?#

Ogni chiamata oltre 4 secondi è considerata non riuscita e il cliente riceve la segnalazione di un problema tecnico. Con 5 errori in 60 secondi le chiamate sono sospese per 60 secondi e il team Flow-e riceve un avviso; le altre funzioni dell'assistente non sono interessate.

Come si gestisce una modifica dell'API?#

Le modifiche all'API vanno comunicate in anticipo, per consentire l'aggiornamento dell'adattatore. Fino all'aggiornamento l'assistente segnala un problema tecnico; le altre funzioni del sito non sono interessate. Contatti: team@looma.company.