Invoices

Create an invoice

You create an invoice with one call to the Invoice Tools API. Waya validates it in real time and answers 201 with the created invoice, or with an error code that tells you what to correct. Every call needs an authorization token, so authenticate first.

This minimal request invoices a mocked test individual for four hours of consultation. Waya looks the debtor up by national identifier and uses their registered address. The lookup operation (opens in a new tab) in Swagger lists the test identifiers.

curl --request POST \
  --url 'https://api.sandbox.waya.se/v4/rest/invoice' \
  --header 'Authorization: Bearer <authorization-token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "externalNumber": "INV-1001",
    "debtor": {
      "nationalIdentifier": {
        "number": "194107102222",
        "countryCode": "SE"
      }
    },
    "rows": [
      {
        "text": "Consultation services",
        "unit": "h",
        "unitPrice": 800.00,
        "quantity": 4,
        "vatPercentage": 25.0,
        "priceExcludingVat": true
      }
    ]
  }'

Change externalNumber each time you run it, because it must be unique. The identifier is a mocked individual that exists in non-production environments only, so use a real debtor in production. A successful call answers 201, and Response lists the fields to know first. You can also find the new invoice in Insight (opens in a new tab).

Swagger describes every field of the request: the debtor, the rows and the optional fields (opens in a new tab), and the delivery methods (opens in a new tab).

Address lookup

Use the lookup operation to check an identifier, or to show the registered address, before you invoice.

curl --request GET \
  --url 'https://api.sandbox.waya.se/v4/rest/legal-entity/SE/194107102222' \
  --header 'Authorization: Bearer <authorization-token>'

In non-production environments, only mocked individuals and a few real organizations can be looked up. The lookup operation (opens in a new tab) in Swagger lists them.

Your own invoice PDF

Normally Waya produces the invoice PDF. The exception is a client that uses Waya's reminder or collection services without the invoice service. You then create the invoice with sendAs set to REMINDER or DEBT_COLLECTION. Waya did not produce the original invoice, so you supply its PDF. Waya makes the PDF available to the debtor online, and prints it on the back of reminders and collection letters. You can send the PDF in attachments when you create the invoice, as Swagger (opens in a new tab) describes.

After the invoice is created

You can also set the PDF afterwards. The body is the PDF file itself, not JSON:

curl --request PUT \
  --url 'https://api.sandbox.waya.se/v4/rest/invoice/<invoice-id>/pdf' \
  --header 'Authorization: Bearer <authorization-token>' \
  --header 'Content-Type: application/octet-stream' \
  --data-binary '@invoice.pdf'

After sending shows how to retrieve an invoice PDF.

Where fields print

Invoices that Waya sends follow one template. The drawing shows its layout with placeholder text. The logo, the issuer, the payment details and the footer come from the client's settings, not from the request.

Marker 2 is the reference grid. It prints only the fields you send, so a field that you leave out leaves no gap. The template applies a limit of 50 characters to each printed reference field, so keep the debtor's customer number (Kundnummer), your references, order numbers, terms of delivery and marking within it. yourReferenceId, ourReferenceId and project are not printed.

A row with only a text prints as a line of text, like the first row in the drawing. invoiceDate prints as Datum and dueDate as Förfallodag. Waya sets the invoice number and the OCR number.

For Peppol and other e-invoices, use edi.yourReference and edi.yourOrderNumber.

Validate the sums

Send your own totals in sumValidation, and Waya compares them with its own calculation from the data in the request. It catches rounding differences between your system and Waya before an invoice goes out. You can validate the whole invoice, each row, or both.

The allowed difference is set for each client. Swagger (opens in a new tab) describes the totals that you can send.

Response

A successful call answers 201 with the invoice, wrapped in data. These are the fields to know first:

Store only the id. It is the only value your system needs to keep, and you can fetch everything else when you need it, as After sending describes. Keep the entity type with the ID if you store IDs of several types, as Entity IDs (opens in a new tab) in Swagger explains.

Reservations

A reservation lets you create an invoice and hold it back. Create it with "reservation": true. Waya creates it, but does not send it until you finalize it. Until then you can replace or delete it:

Replace is a full replacement, so send "reservation": true again to keep the invoice held back. Swagger describes finalizing as setting reservation to false, so a Replace body with reservation set to false or left out finalizes the invoice and sends it.

curl --request PUT \
  --url 'https://api.sandbox.waya.se/v4/rest/invoice/<invoice-id>/finalize' \
  --header 'Authorization: Bearer <authorization-token>'

If a request fails, Errors explains how to read the error code.