Getting started

To get up and running with our API's, you will need to learn a bit about our authentication and select your tools for testing and developing.

Prerequisites

Before you start, make sure you have:

• Subscription key

• Client id and secret

• Organization number

• Access to Postman (or any REST client)

Don't have these yet? Contact our support team first

Learn our Authentication model

You need to understand how our API authentication model works

>> Auth documentation

Testing API with Postman

Read this documentation about how to setup and test with Postman

>> Postman help

Create your first invoice (Mini project)

Here is a micro-journey to get you up an running with Sales API

Create a Contact

URL

POST https://apim.talenom.com/{{region}}/sales/v1/{{organizationNumber}}/contacts

Body

{    
     "organizationNumber": 14222,
     "type": "Consumer",
     "number": "0",
     "name": "John Doe",
     "currency": "EUR",
     "InvoiceLanguage": "fi-FI",
     "defaultReceivableAccountNumber": "1701",
     "invoicingAddress": {
     "address1": "Doe street 1",
     "country": "FI",
     "postalCode": "00100",
     "postOffice": "Helsinki"
    }
}

Save the returned contactId

Create a draft invoice

URL

POST https://apim.talenom.com/{{region}}/sales/v1/{{organizationNumber}}/invoices?contactId={{contactId}}

Body: not needed

Save the returned invoiceVersion and rowVersion at least, but at this point it's good to save the whole body that the endpoint returns, it can be used in next step

Add line items to the invoice

Please note that the row and invoice total sums are automatically calculated by using the quantity and pricePerUnit (or PricePerUnitTaxIncluded) from lineItems

URL

PUT https://apim.talenom.com/{{region}}/sales/v1/{{organizationNumber}}/invoices/{{invoiceId}}

Body (two alternatives)

You can either copy the POST Invoice response and add this bare minimum line item

{
     "type": "Product",
     "productName": "Thingy",
     "quantity": 5.0000,
     "pricePerUnit": 10.00000000000,
     "salesAccountNumber": 3000,
     "taxPercent": 24.00,
 }

OR you an copy this whole body below with lineItems included. Please note that the invoiceId and invoice rowVersion along with proper dates should be updated before sending the request.

{
     "id": "{{invoiceId}}",
     "rowVersion": "{{invoiceRowVersion}}",
     "organizationNumber": 14222,
     "number": 0,
     "status": "Draft",
     "type": "Normal",
     "invoiceOrigin": "Integration",
     "voucherNumber": "0",
     "voucherType": "39",
     "date": "2024-05-10",
     "dueDate": "2024-05-10",
     "originalDueDate": null,
     "remarkTime": 8,
     "paymentTerm": 0,
     "overdueInterest": 10.00,
     "referenceNumber": "",
     "createdDateUtc": "2024-05-10T12:29:33.3946799Z",
     "updatedDateUtc": "2024-05-10T12:29:33.9919439Z",
     "approvedDate": null,
     "sentDate": null,
     "shipMode": "SelfDelivery",
     "creditedInvoiceNumber": "",
     "cashDiscountDate": null,
     "cashDiscountPercent": 0.00,
     "currency": "EUR",
     "exchangeRate": 1.0,
     "currencyTotal": 0.0,
     "currencyTotalTax": 0.0,
     "currencyTotalWithoutTax": 0.0,
     "currencyPaidTotal": 0.0,
     "currencyUnpaidTotal": 0.0,
     "accountingCurrencyTotal": 0.0,
     "accountingCurrencyTotalTax": 0.0,
     "accountingCurrencyTotalWithoutTax": 0.0,
     "accountingCurrencyPaidTotal": 0.0,
     "accountingCurrencyUnpaidTotal": 0.0,
     "recipientContact": {
         "name": "John Doe",
         "nameExtension": "",
         "type": "Consumer",
         "businessId": "",
         "vatId": "",
         "invoicingAddress": {
             "address1": "Doe street 1",
             "address2": "",
             "country": "FI",
             "postalCode": "00100",
             "postOffice": "Helsinki"
         },
         "deliveryAddress": {
             "address1": "",
             "address2": "",
             "country": "",
             "postalCode": "",
             "postOffice": ""
         },
         "deliveryLocation": "",
         "eInvoiceIdentifier": "",
         "eInvoiceIntermediator": null,
         "isEmailInvoicingInUse": false,
         "invoicingEmailAddress": "",
         "emailInvoicingSendType": "Link",
         "invoiceLanguage": "fi-FI"
     },
     "message": "",
     "generalMessage": "",
     "contactSpecificMessage": "",
     "ourReference": "",
     "yourReference": "",
     "orderNumber": null,
     "orderDate": null,
     "deliveryDate": null,
     "comment": "",
     "isDebtCollectionBlocked": false,
     "isPaymentReminderBlocked": false,
     "receivableAccountNumber": 1701,
     "lineItems": [
         {
     "type": "Product",
     "productName": "Thingy",
     "quantity": 5.0000,
     "pricePerUnit": 10.00000000000,
     "salesAccountNumber": 3000,
     "taxPercent": 24.00,
 }
 ],
     "financing": {
         "bankAccountNumber": "",
         "iban": "",
         "bic": "",
         "message": "",
         "messageSentDate": null
     },
     "reminders": [],
     "debtCollection": {
         "collectionBillingDate": null,
         "collectionShipDate": null,
         "isCollectionOrderGenerated": false,
         "collectionFee": 0.0,
         "collectionInterest": 0.0
     },
     "attachments": [],
     "sender": null
 }

Deliver the invoice

URL

POST https://apim.talenom.com/{{region}}/sales/v1/{{organizationNumber}}/invoices/{{invoiceId}}/deliver

Body

{
   "shipMode": "SelfDelivery"
}

Your invoice is now finalized and ready to be downloaded!

Bonus: Download the PDF

URL

GET /v1/{{organizationNumber}}/invoices/{{invoiceId}}/download?downloadAttachments=false

Save the PDF and show it off. You earned it.

You Made It!

You just:

• Created a customer

• Issued your first invoice

• Delivered it electronically (well not really, we used SelfDelivery method)

• Downloaded the final PDF
  

Now it's time to pat your back!