API

Tipo di servizio

Ogni vendita porta un tipo di servizio. Il valore parte esattamente com'è definito: minuscolo, senza accenti, senza traduzione — non lo normalizziamo mai. I valori ammessi sono questi tre, uguali per tutti i punti vendita collegati:

Quale dei tre esce lo decide ogni negozio dal proprio pannello, associando a ognuno le categorie o le etichette del suo catalogo: due punti vendita diversi arrivano allo stesso valore per strade diverse, e ognuno usa quelli che gli servono. Una vendita che non corrisponde a nessuna regola parte come standard.

Verificare la firma

Ogni consegna porta x-omniflow-signature: l'HMAC-SHA256 del corpo, in esadecimale, calcolato con il segreto ricevuto alla registrazione. Firma il corpo grezzo, non il JSON riserializzato: uno spazio di differenza e la firma non torna.

import { createHmac, timingSafeEqual } from 'node:crypto'

function firmaValida(corpoGrezzo, intestazione, segreto) {
  const attesa = createHmac('sha256', segreto).update(corpoGrezzo).digest('hex')
  const data = String(intestazione).replace(/^sha256=/, '')
  const a = Buffer.from(attesa)
  const b = Buffer.from(data)
  return a.length === b.length && timingSafeEqual(a, b)
}

Chi preferisce qualcosa di più semplice può chiedere al negozio di configurare una API key o un Bearer token al posto della firma: li mandiamo in un'intestazione a scelta.

Come ci comportiamo

Idempotenza

Lo stesso scontrino non viene mai trasmesso due volte: la chiave è order_id. Se lo ricevi due volte per un nostro ritentativo, scarta il secondo.

Ritentativi

Se non rispondi o rispondi con un errore, la transazione resta registrata da noi con il suo payload e viene ritentata automaticamente alle vendite successive, per sette giorni. Il negozio può anche ripeterla a mano dal pannello.

Tempo di risposta

Chiudiamo la richiesta dopo cinque secondi. Oltre quel limite la consideriamo fallita e la ritentiamo: alla cassa c'è un cliente che aspetta lo scontrino, e non può aspettare il tuo server.

Vendite senza anagrafica

Molti scontrini al banco non hanno un cliente registrato. Senza nome e senza recapito non li inviamo: restano segnati da noi come ignorati. Se li vuoi comunque, il negozio può abilitarli.

Cosa risponderci

• 2xx — consegnata, non ritentiamo.
• 4xx — payload rifiutato: non ritentiamo e segnaliamo l'errore nel pannello del negozio. Un corpo con il motivo aiuta a capire cosa correggere.
• 5xx o nessuna risposta — problema temporaneo: ritentiamo.

Rileggere le transazioni

Se eri spento, o preferisci controllare invece di aspettare, le vendite già trasmesse si rileggono in qualsiasi momento.

curl "https://pos.omniflow.it/api/v1/transactions?since=2026-09-01T00:00:00Z&limit=50" \
  -H "Authorization: Bearer omf_live_..."

{
  "data": [ { "order_id": "...", "service_type": "sarta", "...": "..." } ],
  "has_more": false
}

Ordine dal più recente. Ogni voce porta anche delivery_status e sent_at, così sai se quella consegna era andata a buon fine.

Se qualcosa non torna

• 401 su ogni chiamata — la chiave è stata revocata o rigenerata: chiedine una nuova al negozio.
• 429 con Retry-After: 60 — hai superato le 120 chiamate al minuto concesse a una chiave. È il freno contro l'integrazione che va in ciclo: aspetta il minuto e riprendi. Se ti serve di più, scrivici.
• Non arriva niente — verifica con GET /v1/webhooks che l'indirizzo registrato sia quello giusto, e che risponda a un POST in meno di cinque secondi.
• La firma non torna — quasi sempre è il corpo riserializzato: firma la stringa esatta ricevuta, prima di qualsiasi parsing.
• Vedi solo alcune vendite — quelle senza anagrafica cliente non partono, salvo che il negozio le abiliti.