SDK Go per Italia
github.com/corp-merch/sdk-go — client context-aware, paginatori con generics, errori tipizzati per Italia.
Architettura — Installazione e init per Italia
go get github.com/corp-merch/sdk-go. Init: cm := corpmerch.New(os.Getenv("CM_KEY"), corpmerch.WithCountry("Italia")). L'opzione country applica IVA 22% e instrada le fatture via SdI (hub Milano). Go 1.22+; zero dipendenze esterne nel core (net/http ed encoding/json). Drop-in per qualsiasi router chi/gin/echo.
Come integrarlo — Quickstart con context
ctx, cancel := context.WithTimeout(ctx, 10*time.Second); defer cancel(). order, err := cm.Orders.Create(ctx, &corpmerch.OrderCreateParams{IdempotencyKey: uuid.NewString(), Buyer: &corpmerch.Buyer{VatID: "EU…"}, Lines: []corpmerch.Line{{SKU: "TSH-001", Qty: 200}}}). Paginazione con generics: iter := cm.Catalog.List(ctx, params); for iter.Next() { item := iter.Current() }.
Operatività e casi limite — Errori tipizzati e firma webhook
Gli errori implementano errors.Is e errors.As. Controlla con if errors.Is(err, corpmerch.ErrRateLimit) { … }. Verifica webhook: event, err := cm.Webhooks.ConstructEvent(body, signature, secret) con confronto a tempo costante via subtle.ConstantTimeCompare. ID di notifica Sistema di Interscambio (SdI) disponibili come event.Invoice.AcknowledgementID.
Domande frequenti
Versioni Go?
1.22 e 1.23 in CI; 1.21 può funzionare ma non garantito.
Dipendenze?
Il core ha zero dipendenze esterne. I moduli opzionali (otel) portano OpenTelemetry.
Generics?
Sì — paginatori Iterator[T] generici con item tipizzati. Migliora la DX rispetto a reflection.
Firma webhook?
cm.Webhooks.ConstructEvent(body, sig, secret) — confronto a tempo costante via subtle.ConstantTimeCompare.
IVA 22% e SdI?
Lato server via WithCountry('Italia'). ID notifica SdI sui tipi evento fattura.