Documentation
¶
Overview ¶
Package ksef provides a Go client for Poland's National e-Invoicing System (Krajowy System e-Faktur) 2.0 API.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AuthenticationError ¶
type AuthenticationError struct {
// Cause is the underlying KSeFError, if the server returned one.
Cause *KSeFError
}
AuthenticationError is returned when the KSeF API rejects a request due to invalid or expired credentials (HTTP 401 / 403).
func (*AuthenticationError) Error ¶
func (e *AuthenticationError) Error() string
Error implements the error interface.
func (*AuthenticationError) Unwrap ¶
func (e *AuthenticationError) Unwrap() error
Unwrap returns the underlying error so errors.As can traverse the chain.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is the entry point for all KSeF API operations. Create one with NewClient and then use it to open sessions, submit invoices, and query invoice status.
Client is safe for concurrent use by multiple goroutines.
func NewClient ¶
func NewClient(env Environment, opts ...Option) (*Client, error)
NewClient creates a Client targeting the given environment. Zero or more Option values can be passed to override defaults (HTTP client, logger, retry behaviour).
Example:
client, err := ksef.NewClient(ksef.Test,
ksef.WithLogger(slog.Default()),
ksef.WithRetryConfig(5, time.Second),
)
func (*Client) Environment ¶
func (c *Client) Environment() Environment
Environment returns the environment this client is configured for.
type Environment ¶
type Environment int
Environment identifies the KSeF deployment to connect to.
const ( // Test is the KSeF test environment. Use this during development. Test Environment = iota // Demo is the KSeF demo environment. Demo // Production is the live KSeF production environment. Production )
func (Environment) BaseURL ¶
func (env Environment) BaseURL() string
BaseURL returns the root URL for the environment's API, without a trailing slash. It panics if env is not a recognised Environment value.
func (Environment) String ¶
func (env Environment) String() string
String returns a human-readable name for the environment.
type ExceptionDetail ¶
type ExceptionDetail struct {
// ExceptionCode is the numeric KSeF error code (e.g. 21405).
ExceptionCode int32
// ExceptionDescription is the human-readable description of the error,
// typically in Polish.
ExceptionDescription string
// Details contains optional additional context provided by the API.
Details []string
}
ExceptionDetail represents a single error entry returned by the KSeF API inside an ExceptionResponse body.
type KSeFError ¶
type KSeFError struct {
// HTTPStatus is the HTTP response status code (e.g. 400, 404).
HTTPStatus int
// ReferenceNumber is the KSeF correlation identifier from the response,
// if present.
ReferenceNumber string
// Exceptions contains the individual error entries reported by the API.
Exceptions []ExceptionDetail
}
KSeFError is returned when the KSeF API responds with a non-2xx status and an ExceptionResponse body. It preserves the full list of exception details so callers can inspect individual error codes.
type Option ¶
type Option func(*Client)
Option is a functional option that configures a Client.
func WithHTTPClient ¶
WithHTTPClient replaces the default HTTP client used for all API calls. The supplied client must not be nil.
func WithLogger ¶
WithLogger sets the structured logger used by the client for debug and informational output. Pass nil to disable logging entirely.
func WithRetryConfig ¶
WithRetryConfig controls how the client retries failed requests. maxRetries is the maximum number of additional attempts after the first failure (0 means no retries). baseDelay is the initial back-off duration; each subsequent retry doubles it.
type RateLimitError ¶
type RateLimitError struct {
// RetryAfter is the duration the caller should wait before retrying.
// It is derived from the Retry-After response header when present.
RetryAfter time.Duration
}
RateLimitError is returned when the KSeF API responds with HTTP 429 (Too Many Requests). The caller should wait at least RetryAfter before retrying.
func (*RateLimitError) Error ¶
func (e *RateLimitError) Error() string
Error implements the error interface.
type SessionError ¶
type SessionError struct {
// Message describes what went wrong.
Message string
// Cause is the underlying error, if any.
Cause error
}
SessionError is returned when an operation fails because the KSeF session is in an invalid state (e.g. already closed, not yet opened).
func (*SessionError) Error ¶
func (e *SessionError) Error() string
Error implements the error interface.
func (*SessionError) Unwrap ¶
func (e *SessionError) Unwrap() error
Unwrap returns the underlying error so errors.As can traverse the chain.
type ValidationError ¶
type ValidationError struct {
// Field identifies the field or path that failed validation, if known.
Field string
// Message describes the validation failure.
Message string
}
ValidationError is returned when input data fails client-side or server-side validation before or during an API call.
func (*ValidationError) Error ¶
func (e *ValidationError) Error() string
Error implements the error interface.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package auth provides authentication mechanisms for the KSeF API.
|
Package auth provides authentication mechanisms for the KSeF API. |
|
Package crypto provides cryptographic helpers for the KSeF SDK.
|
Package crypto provides cryptographic helpers for the KSeF SDK. |
|
Package fa3 provides Go types for the FA(3) e-invoice XML schema used by the Polish National e-Invoicing System (KSeF).
|
Package fa3 provides Go types for the FA(3) e-invoice XML schema used by the Polish National e-Invoicing System (KSeF). |
|
Package invoice provides invoice submission and status operations for KSeF online sessions.
|
Package invoice provides invoice submission and status operations for KSeF online sessions. |
|
Package session provides KSeF session management for online and batch modes.
|
Package session provides KSeF session management for online and batch modes. |