Documentation
¶
Overview ¶
Package session provides KSeF session management for online and batch modes.
Index ¶
Constants ¶
const (
// FormCodeFA3 identifies the FA(3) standard Polish VAT invoice schema.
FormCodeFA3 = "FA(3)"
)
Common form code identifiers for use with Manager.OpenOnline.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type EncryptionInfo ¶
type EncryptionInfo struct {
// EncryptedSymmetricKey is the 32-byte AES-256 key encrypted with
// RSA-OAEP (SHA-256), using the KSeF environment's public key.
EncryptedSymmetricKey []byte
// InitializationVector is the 16-byte IV for AES-256-CBC encryption.
InitializationVector []byte
// SymmetricKey is the plaintext 32-byte AES-256 key. Set this so that
// the resulting OnlineSession can encrypt invoices without the caller
// having to track the key separately.
SymmetricKey []byte
}
EncryptionInfo holds the pre-computed encryption parameters required when opening a KSeF session. Use the crypto package to generate these values from a random AES-256 key and the KSeF environment's RSA public key.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager provides methods for opening KSeF online sessions.
func NewManager ¶
func NewManager(hc *httpclient.Client) *Manager
NewManager creates a Manager using the given internal HTTP client.
func (*Manager) OpenOnline ¶
func (m *Manager) OpenOnline(ctx context.Context, accessToken, formCode string, enc EncryptionInfo) (*OnlineSession, error)
OpenOnline opens a new interactive session on the KSeF API and returns the resulting OnlineSession.
accessToken must be a valid JWT access token obtained from the auth package.
formCode identifies the invoice schema; use the FormCode* constants declared in this package (e.g. FormCodeFA3 for standard Polish VAT invoices).
enc must contain the pre-computed encryption parameters. Generate them with the crypto package using a freshly generated random AES-256 key and the KSeF environment's RSA public key.
type OnlineSession ¶
type OnlineSession struct {
// ReferenceNumber is the 36-character session identifier assigned by KSeF.
ReferenceNumber string
// ValidUntil is the timestamp after which KSeF will automatically expire
// the session if it has not been terminated by the caller.
ValidUntil time.Time
// AESKey is the plaintext AES-256 key used to encrypt invoices within this
// session. It is set from EncryptionInfo.SymmetricKey when opening the session.
AESKey []byte
// IV is the 16-byte initialization vector sent to KSeF at session open.
// It must be used (unchanged) when encrypting every invoice in this session.
IV []byte
// contains filtered or unexported fields
}
OnlineSession represents an open KSeF interactive session. All invoice submissions within a session must be completed before calling Terminate.
OnlineSession is not safe for concurrent use by multiple goroutines.
func (*OnlineSession) AccessToken ¶
func (s *OnlineSession) AccessToken() string
AccessToken returns the JWT access token associated with this session.
func (*OnlineSession) Status ¶
func (s *OnlineSession) Status(ctx context.Context) (*SessionStatus, error)
Status fetches and returns the current state of the session.
func (*OnlineSession) Terminate ¶
func (s *OnlineSession) Terminate(ctx context.Context) (*SessionStatus, error)
Terminate closes the session and returns its state immediately after the close request is accepted. The status will be StatusClosed (170) at this point; KSeF processes the session asynchronously and transitions to StatusProcessedOK (200) once done. Poll OnlineSession.Status until you see StatusProcessedOK to retrieve the UPO.
func (*OnlineSession) WaitUntilActive ¶
func (s *OnlineSession) WaitUntilActive(ctx context.Context) error
WaitUntilActive polls the session status endpoint with exponential backoff until the session reaches StatusOpened (100), indicating it is ready to accept invoice submissions. It returns an error if the session enters a terminal error state or the 10-second deadline is exceeded.
OpenOnline calls this automatically; callers should not need to call it directly unless re-checking a session obtained from an external reference.
type SessionStatus ¶
type SessionStatus struct {
// Status holds the numeric status code and its description.
Status StatusInfo
// DateCreated is when the session was created.
DateCreated time.Time
// DateUpdated is when the session state was last updated.
DateUpdated time.Time
// ValidUntil is the session expiry time; nil once the session is closed.
ValidUntil *time.Time
// UPO holds the official confirmation download information. It is
// populated once the session reaches StatusProcessedOK.
UPO *UPO
// InvoiceCount is the total number of invoices submitted to the session.
InvoiceCount *int32
// SuccessfulInvoiceCount is the number of invoices that passed processing.
SuccessfulInvoiceCount *int32
// FailedInvoiceCount is the number of invoices that failed processing.
FailedInvoiceCount *int32
}
SessionStatus describes the current or final state of a KSeF session.
type StatusCode ¶
type StatusCode int32
StatusCode represents a KSeF session status code.
const ( // StatusOpened indicates an interactive session has been opened. StatusOpened StatusCode = 100 // StatusClosed indicates the interactive session has been closed. StatusClosed StatusCode = 170 // StatusProcessedOK indicates the session was processed successfully // and the UPO is available. StatusProcessedOK StatusCode = 200 // StatusDecryptionError indicates the server failed to decrypt the // provided symmetric key. StatusDecryptionError StatusCode = 415 // StatusCancelled indicates the session was cancelled — no invoices // were submitted before the timeout expired. StatusCancelled StatusCode = 440 // StatusValidationError indicates that no invoice in the session // passed validation. StatusValidationError StatusCode = 445 )
type StatusInfo ¶
type StatusInfo struct {
// Code is the numeric KSeF status code.
Code StatusCode
// Description is the human-readable status message, typically in Polish.
Description string
// Details contains optional additional context provided by the API.
Details []string
}
StatusInfo describes the code and human-readable description of a session state.
type UPO ¶
type UPO struct {
// Pages contains one or more downloadable UPO pages.
Pages []UPOPage
}
UPO is the Urzędowe Potwierdzenie Odbioru — the official receipt issued by KSeF once a session has been successfully processed.
type UPOPage ¶
type UPOPage struct {
// ReferenceNumber is the UPO page reference number.
ReferenceNumber string
// DownloadURL is the URL to fetch the UPO page; no auth token is required.
DownloadURL string
// ExpiresAt is when the download URL becomes invalid.
ExpiresAt time.Time
}
UPOPage contains a single-page download URL for the UPO document.
Source Files