.NET client library for SuperFaktura API.
Codes are wrapped as .net Shared Library. So you can download them and include into your programs or .dll libraries.
Library uses System.Net.Http.HttpClient as communication layer and Newtonsoft.Json for serialization and deserialization
Implementation used by FinStat.sk
- SuperFakturaAPI.NET/ - the library as a .NET Shared Project (
SuperFakturaAPI.NET.projitems), import it into your project - SuperFaktura/ - NuGet package project (
SuperFaktura, netstandard2.0) - SuperFaktura.Tests/ - tests: offline
SerializationTest(no credentials) and integration tests against the SuperFaktura sandbox (credentials inSuperFaktura.Tests/Properties/launchSettings.json, not committed) - SuperFaktura.slnx - solution
The main api client class SuperFaktura has this hierarchy. Most of used classes is from Birko.SuperFaktura namespace
Main class. Ensures the propper API calling, serialization of request parameters and deserialization of response from SuperFaktura servers. It ensures that the delay between api calls is more than 1 second.
Localized classes
SuperFakturaCZandSuperFakturaATfor country specific endpoints
Sandbox classes
SuperFakturaSandboxandSuperFakturaSandboxCZfor testing endpoints
- EnsureSuccessStatusCode - boolean, default true. Switches the behaviour if System.Net.Http.HttpClient should raise exception for not succesfull response
- BankAccounts - instance of
BankAccountsclass, description bellow - CashRegisters - instance of
CashRegistersclass, description bellow - Clients - instance of
Clientsclass, description bellow - ContactPersons - instance of
ContactPersonsclass, description bellow - Expenses - instance of
Expensesclass, description bellow - Exports - instance of
Exportsclass, description bellow - Invoices - instance of
Invoicesclass, description bellow - Other - instance of
Otherclass, description bellow - Stock - instance of
Stockclass, description bellow - Tags - instance of
Tagsclass, description bellow - ValueLists - instance of
ValueListsclass, description bellow
- SuperFaktura(string email, string apiKey, string apptitle = null, string module = "API", int? companyId = null) - constructor. email and apiKey are mandatory parameters. Given from SuperFaktura.
- ResponseByChecksum(string checksum) - returns the original response of a request sent with given
checksum(up to 3 months back), ornullwhen no such request reached the server. Seechecksumparameter ofInvoices.Add,Expenses.AddandCashRegisters.AddItem
API errors (also HTTP 4xx/5xx with an API error body) are thrown as Birko.SuperFaktura.Exceptions.Exception with Error (API error code), ErrorMessage and ResponseMessage. Newer endpoints (e.g. Peppol) always answer "error": 1 and identify the error by a string ErrorCode (e.g. peppol.precheck_failed), with details in ErrorData (the response data as JToken, e.g. ErrorData["issues"]; null when empty). A response that is not JSON throws Exceptions.ParseException.
Request properties left null are not sent. Edit methods therefore change only the properties that were set and the server keeps the stored values.
Class that wrappes bank accounts API
- List - returns lists of bank accounts
- Add(Request.BankAccounts.BankAccount account) - adds new bank account
- Edit(int id, Request.BankAccounts.BankAccoun account) - edits bank account with given
id - Delete(int id) - deletes bank account with given
id
Class that wrappes cash registers API calls
- List - returns lists of cash registers
- View(int id) - get cash register detail according given
id - ListItems(Request.CashRegister.Filter filter) - gets items of cash register
filter.IDaccordingfilter, together with the cash register - AddItem(Request.CashRegister.CashRegisterItem item, string checksum = null) - adds cash register item. Optional
checksum(own unique identifier, max 32 chars) forResponseByChecksum - DeleteItem(int id) - deletes cash register item with given
id - DeleteItems(IEnumerable<int> ids) - deletes cash register items with given list of
ids - Download(int id) - get PDF receipt according cash register item with given
idas byte array
Class that wrappes clients API calls
- List(Request.Client.Filter filter, bool listInfo = true) - returns lists of clients according
filter - Add(Request.Client.Client client, int[] tags = null) - add new client, optional 'tags'
- Edit(int id, Request.Client.Client client, int[] tags = null) - add client according given
id. Optionaltagscan be specified - View(int id) - get client detail according given
id - Delete(int id) - deletes client with given
id
Class that wrappes contact people API calls
- List(int id) - returns list of contacts according given client
id - Add(Request.ContactPersons.ContactPerson) - add new contact person
- Delete(int id) - deletes contact person with given
id
Class that wrappes all API calls for expenses handling in SuperFaktura.
- List(Request.Expense.Filter filter, bool listInfo) - gets list of expenses according
filter - Add(Request.Expense.Expense expense, Request.Expense.ExpenseItem[] items = null, Request.Client.Client client = null, Request.Expense.Extra extra = null, int[] tags = null, string checksum = null) - adds new expense entry. Optional
items,client,extra,tagsandchecksum(own unique identifier forResponseByChecksum) can be specified - Edit(Request.Expense.Expense expense, Request.Expense.ExpenseItem[] items = null, Request.Client.Client client = null, Request.Expense.Extra extra = null, int[] tags = null) - edits expense with
expense.ID. Optionalitems,client,extraandtagscan be specified - View(int id) - get expense detail with given
id - Delete(int id) - deletes expense with given
id - AddPayment(Request.Expense.Payment payment) - adds payment to expense
- DeletePayment(int id) - deletes expense payment with given payment
id - AddRelatedItem(Request.RelatedItem relatedItem) - adds related item to expense
- DeleteRelatedItem(int id) - deletes related item with given relation
id - DownloadAttachments(int expenseID, int? attachementID = null) - downloads attachments for given expense
expenseIDas byte array, optionalattachementIDcan be specified or all attachments will be downloaded as zip file - DeleteExpenseItem(int expenseID, IEnumerable deleteItemIDS, bool createBlank = true) - deletes expense items according given list of
deleteItemIDSfrom expense with givenexpenseID. WithcreateBlankan empty item is created when all items are deleted (an expense needs at least one item)
Class that wrappes exports API calls
- Export(Request.Export.ExportData export) - creates an export request with given
exportdata - Status(int id) - show export status according given
id - Download(int id) - downloads export according given
idas byte array
Class that wrappes invoice API calls
- List(Request.Invoice.Filter filter, bool listInfo = true) - gets list of invoices according
filter - Add(Request.Invoice.Invoice invoice, Client client, Request.Invoice.Item[] items, int[] tags = null, Request.Invoice.InvoiceSettings setting = null, Request.Invoice.Extra extra = null, Request.Invoice.MyData myData = null, string checksum = null) - creates new invoice. Optional
tags,setting,extra,myDataandchecksum(own unique identifier, e.g. order number, max 32 chars, forResponseByChecksum) can be specified - Edit(Request.Invoice.Invoice invoice, Client client = null, Request.Invoice.Item[] items = null, int[] tags = null, Request.Invoice.InvoiceSettings setting = null, Request.Invoice.Extra extra = null, Request.Invoice.MyData myData = null) - updates invoice with
invoice.ID, only properties that are set are changed. Returns the full invoice detail. Items withIDare updated and items withoutIDare added; items that are left out are not deleted by the API, remove them withDeleteItem - View(int id) - gets invoice detail according
id - ListDetails(int[] ids) - gets invoice details according given list of invoice
id - SetInvoiceLanguage(int id, string language) - sets the default language for given invoice
id - Download(int id, string token, string language, bool? signature = null, bool? bySquare = null, bool? paypal = null) - gets the PDF for given invoice
idas byte array. You can specify some options about parts displayed on invoice - Delete(int id) - deletes invoice with given
id - WillNotBePaid(int id) - sets invoice with given
idas not be paid - SendEmail(Request.Invoice.Email email) - sends Email with invoice
- MarkAsSentViaMail(Request.Invoice.MarkEmail email) - marks sended email with invoice
- SendPost(Post post) - send invoice throw regular post
- MarkAsSent(int id) - marks invoice as send
- SendPeppol(int id, string webhookUrl = null, string webhookSecret = null) - queues sending of invoice with given
idas eInvoice over the Peppol network (the company must have Peppol sending enabled). ReturnsPeppolSendResultwithOperationIDandStatus; delivery is asynchronous. OptionalwebhookUrl(public HTTPS URL, redirects are not followed) receives the final outcome, signed whenwebhookSecret(1-512 chars) is set - see Peppol webhook. Errors carryErrorCodefromPeppolErrorCode - GetPeppolStatus(int id) - gets the latest Peppol sending status of invoice with given
id(PeppolSendStatus:Status,ProviderStatus,FailureCode, ...). A failed send isStatus = "failed", not an exception.ProviderStatus = "accepted"is the final positive outcome - DeleteItem(int id, int itemid) - deletes item with
itemidfrom invoice with givenid - DeleteItem(int id, int[] itemid) - deletes items according given list of
itemidfrom invoice with givenid - AddPayment(Request.Invoice.Payment payment) - adds payment to invoice
- DeletePayment(int id) - deletes invoice payment with given payment
id - AddRelatedItem(Request.RelatedItem relatedItem) - adds related item to expense
- DeleteRelatedItem(int id) - deletes related item with given relation
id - DownloadReceipt(int id) - downloads receipt according given invoice
idas byte array
Birko.SuperFaktura.PeppolWebhook helps the receiver of the webhookUrl passed to SendPeppol:
- VerifySignature(string timestamp, byte[] body, string signature, string secret) (or
string body) - checks theX-SuperFaktura-Webhook-Signatureheader against theX-SuperFaktura-Webhook-Timestampheader and the raw request body (re-serialized JSON does not match). Returnsfalsefor a missing or wrong signature - Parse(string body) - reads the body as
PeppolWebhookEvent(EventID,EventType,OccurredAt,DataasPeppolSendStatus) - Header names are available as constants (
TimestampHeader,SignatureHeader,WebhookIdHeader,IdempotencyKeyHeader)
Delivery can be retried: deduplicate by EventID and answer HTTP 2xx also for a duplicate. A document can stay at provider status sent without a callback; use GetPeppolStatus when still waiting.
var body = await ReadRawBodyAsync(request); // byte[]
if (!PeppolWebhook.VerifySignature(request.Headers[PeppolWebhook.TimestampHeader], body,
request.Headers[PeppolWebhook.SignatureHeader], webhookSecret))
{
return Unauthorized();
}
var webhook = PeppolWebhook.Parse(Encoding.UTF8.GetString(body));
if (webhook.Data.ProviderStatus == PeppolProviderStatus.Accepted) { /* delivered */ }Class that wrappes all other API calls
- ListAccounts() - gets list of user accounts
- ListUserCompanies(bool all = false) - gets list of user copmanies. Oprional
allswitch parameter - SendSMS(Request.Other.SMS sms) - sends and SMS
- ListBankAccountMovements(Request.Other.BankMovementFilter filter) - returns all bank account movements according given
filter - ListActivityLogs(string documentType, int documentId, int limit = 10) - returns all log for given
documentTypeanddocumentId. Optional listlimitparameter can be specified
Class that wrappes stock API calls
- List(Filter filter, bool listInfo = true) - gets list of stock items according filter
- Add(Request.Stock.Item item) - adds new stock item
- Edit(int id, Request.Stock.Item item) - edits stock item according
id - View(int id) - gets stock item detail according
id - Delete(int id) - deletes stock item according
id - AddStockMovement(IEnumerable<Request.Stock.Log> items) - adds stock movement logs to stock item
- AddStockMovement(Request.Stock.Log item) - adds stock movement log to stock item
- ListStockMovements(int id, Request.PagedParameters filter, bool listInfo = true) - gets stock movements for items item detail according
idand givenfilter
Class that wrappes tags API calls
- List() - gets list of stored tags
- Add(Request.Tags.Tag tag) - adds new tag
- Edit(int id, equest.Tags.Tag tag) - edits tag with
id - Delete(int id) - deletes tag with
id
Class that wrappes lists API calls
- ListCountries() - gets country names and and ids as dictionary
- ListCountriesFull() - gets full Country list
- ListExpenseCategories - gets list of ExpenseCategories
- ListLogos() - gets list of uploaded logos
- ListSequences() - gets available sequences as dictionary
List are stored in Birko.SuperFaktura.Request.ValueLists namespace
- AccountingDetailType - list of accounting types for invoice and expense items (
AccountingDetail.Type) - CashRegisterItemType - cash register items filter types (in / out)
- DeliveryType - list of deliveries types
- DocumentType - list of document types for related items and logs
- ExpenseStatus - list of expense statuses
- ExpenseVersion - list of expense type versions
- ExpenseType - list of expense types
- ExportStatus - list of export statuses
- InvoiceType - list of invoice types
- InvoiceStatus - list of invoice statuses
- LanguageType - list of supported languages
- PaymentType - list of payment types
- PeppolErrorCode -
ErrorCodevalues ofSendPeppolandGetPeppolStatus - PeppolProviderStatus - Peppol provider statuses (
PeppolSendStatus.ProviderStatus) - PeppolStatus - statuses of the Peppol send operation (
PeppolSendResult.Status) - PeriodTypes - list of period types
- RoundingType - list of invoice or expense rounding types
- SequenceType - keys of
ListSequences()(document types of number sequences) - TimeFilterConstants - list of time numeric constants used in some filters
- TimeFilter - list of time string constants used in some filters