​
Introduction

The objective of this guide is to take you through the process of generating a simple PDF invoice you can send to your customers, in tax regimes that don’t require an electronic reporting or invoicing.

For this example we assuming the following conditions:

  • Our company is VAT registered in the UK.

  • We have the basic information about the invoice: date, supplier, customer, and items with their VAT rates to apply to each.

  • Our invoices do not have a sequential code, but we want one that looks like TEST-000001.

  • Customers expect a PDF.

  • We want an email copy of our invoice.

You don’t need to be a developer to use this guide, but you will need to have a bit of experience using the command line and know how to create a text file. For sending requests to the server we use the “curl” command, included with most operating systems. You might however find it easier to use a visual tool for sending HTTP requests like Postman.

We assume here that you’ve already followed the steps in the Authentication guide, and have an access token ready to use.

To give you a heads up, these are the stages we’ll be going through:

  • Build a new workflow with a set of steps to execute

  • Upload a document

  • Create a Job

  • Download the results

Let’s get started.

​
Define a Workflow

A Workflow in Invopop is essentially a list of steps that will be executed one-by-one for an incoming job. Each step is linked with a provider of a given service, like generating a PDF, forwarding invoices to an external tax agency, sending emails, or posting webhooks.

  1. Head to the Workflows section.

  2. Tap ”+ New”.

  3. Then, select Invoice and tap Create Workflow.

  4. Use the Name field to give this new workflow an easy way to be identified, like “Process Invoice”.

In the following sections we’ll run through adding each step.

​
Add Sequential Code

Series are used to assign sequential numbers to documents, typically invoice codes, and guarantee their order.

  1. Tap the ”+” button to add a new step to the workflow.

  2. From the list of providers on the right, find and click on Add Sequential Code.

  3. Ensure the Configuration tab is selected.

  4. Select the “dynamic” sequence option in the select box. This will automatically create a new sequential codes for each combination of Supplier Tax ID Code and invoice series.

  5. Set the “Name” to “Invoices”.

  6. Tap the “Sign document” checkbox at the bottom of the form, this will ensure invoices contain a digital signature.

The configurtion is updated in real-time, so there are no additional steps to perform.

​
Generate PDF

The Invopop PDF Generator is used to convert GOBL documents into human readable PDF files that can be shared with customers.

  1. Tap the ”+” button under the “Add Sequential Code” step.

  2. From the list of providers on the right, find Generate PDF and click.

  3. Tap “Configure” tab.

  4. Choose a language for the invoices and upload a company logo if you have one to hand. Also select or change any of the settings you think might be relevant for you.

​
Send via email

It can be useful to send emails to customers or billing departments with details about the invoices that have been generated. This example utilizes Invopop’s email sending service to process emails. If you want to use your own email domain for sending, checkout the “Resend” step.

  1. Tap the ”+” button under the “Generate PDF” step.

  2. From the list of providers, click Send via Email.

  3. Click “Configure” tab.

  4. Introduce a destination in the “To:” or “BCC:” fields by typing the address either in regular or “mailbox” format. (mailbox format includes name, e.g. John Smith <john.smith@example.com>).

  5. Alter any of the other fields that are appropriate for the email.

  6. Tap the “Automatically add invoice customers” checkbox if you’d like to send copies of emails to customers defined in invoices.

​
Save

Having completed all these sections, you should now have 3 steps in the workflow.

Before leaving, we can check the JSON of the workflow by clicking the toggle next to “Save” in the top bar. This allows us to see and edit the raw JSON workflow definition. It should look like the following:

{
  "name": "New invoice workflow",
  "description": "",
  "steps": [
    {
      "id": "03778480-9081-11ef-b6eb-311cb2655f5d",
      "name": "Add Sequential Code",
      "provider": "sequence.enumerate",
      "summary": "Dynamic · Invoices · 000001",
      "config": {
        "sign": false,
        "padding": 6,
        "start": 1,
        "name": "Invoices"
      }
    },
    {
      "id": "45e65a80-9081-11ef-b6eb-311cb2655f5d",
      "name": "Generate PDF",
      "provider": "pdf",
      "summary": "English",
      "config": {
        "logo_height": 40,
        "locale": "en",
        "date_format": "%Y-%m-%d"
      }
    },
    {
      "id": "4a615b50-9081-11ef-b6eb-311cb2655f5d",
      "name": "Send via Email",
      "provider": "email",
      "summary": "To invoice customers",
      "config": {
        "add_invoice_customer": true,
        "add_invoice_supplier": false,
        "zip_attachments": false,
        "body": "SGVsbG8ge3sgLmN1c3RvbWVyX25hbWUgfX0sCgpQbGVhc2UgZmluZCBhdHRhY2hlZCB5b3VyIGludm9pY2Uge3sgLmZ1bGxfY29kZSB9fSB3aXRoIGRhdGUge3sgLmlzc3VlX2RhdGUgfX0uCgpCZXN0LAp7eyAuc3VwcGxpZXJfbmFtZSB9fQ==",
        "subject": "Invoice {{ .full_code }} from {{ .supplier_name }}"
      }
    }
  ]
}

Return to the visual view, and tap the “Save” button at the top right. In the Workflows list page you should be able to copy the UUID for the new workflow, which we’ll need for later examples.

​
Upload a Document

We’ve prepared a workflow with a set of integrations to process and convert invoices. Our next step is to upload a document to be processed by the workflow and extract the results.

At Invopop we use GOBL as our base format. It’s been purpose built (by us) to make it easy to create business documents using JSON and contain everything needed to be globally compatible.

If you haven’t had chance to read the GOBL Docs, there are two basic concepts that are important to understand:

  1. A GOBL Object represents a payload; an invoice, message, contact details, or some other unit of business data, defined using a JSON Schema that GOBL understands.

  2. A GOBL Envelope is a wrapper around a GOBL Object that adds meta-data like a digest and digital signatures.

At Invopop, we only ever store GOBL Envelopes. This is important as it means we can verify the contents and ensure no changes have been made. Most interfaces and APIs in Invopop however will automatically wrap GOBL Objects inside Envelopes, so you don’t need to worry about it when uploading, but you will need to take this into account when downloading.

In the next steps we’re going to need a sample partial GOBL Invoice document to upload, here’s one we created earlier:

{
  "$schema": "https://gobl.org/draft-0/bill/invoice",
  "currency": "GBP",
  "series": "TEST",
  "supplier": {
    "tax_id": {
      "country": "GB",
      "code": "844281425"
    },
    "name": "BrightTech Solutions Ltd.",
    "emails": [
      {
        "addr": "billing@brighttech.co.uk"
      }
    ],
    "addresses": [
      {
        "num": "123",
        "street": "Innovation Park",
        "locality": "Cambridge",
        "code": "CB1 2AB",
        "country": "GB"
      }
    ]
  },
  "customer": {
    "tax_id": {
      "country": "GB",
      "code": "350983637"
    },
    "name": "GreenWave Energy Ltd.",
    "emails": [
      {
        "addr": "info@greenwave.co.uk"
      }
    ],
    "addresses": [
      {
        "num": "45",
        "street": "Riverside Business Park",
        "locality": "London",
        "code": "SW1A 1AA",
        "country": "GB"
      }
    ]
  },
  "lines": [
    {
      "quantity": 50,
      "item": {
        "name": "Thermal efficient mugs",
        "price": "16.00"
      },
      "taxes": [
        {
          "cat": "VAT",
          "rate": "standard"
        }
      ]
    }
  ]
}

The most important bits of data to take away from this document are the:

  • JSON schema that identifies the GOBL invoice type,

  • series and currency,

  • supplier and customer, with their VAT ID codes, and,

  • lines of items of a given quantity and price to which VAT at a “standard” rate needs to be applied.

Note we used the word partial earlier to describe this document. It’s not a complete and valid GOBL object as it doesn’t contain important details like the invoice code, issue date, or tax totals.

A document without the missing required data cannot be signed. Some workflow steps require envelopes to be signed as this offers guarantees that the information has not been modified. As we’ll see shortly, once uploaded to Invopop, the API and workflow we created earlier will automatically assign an invoice code, issue date, and make the required calculations so it can be signed.

For more details on creating Invoices, see the GOBL Documentation Site. You’ll find more guides there on all the different options and configurations available for invoices, including ways you can build complete GOBL Envelopes with signatures.

Let’s upload this document to the Invopop Silo service:

  1. Copy and paste the JSON above into you favorite text editor.

  2. Save the JSON into a file named invoice.json in a temporary folder you can easily find from the command line (Downloads is usually a safe bet).

  3. Open the Terminal or command line, and enter the temporary directory, e.g. cd ~/Downloads.

  4. Upload the document using the following Curl command:

curl -H "Authorization: Bearer $INVOPOP_TOKEN" -X POST -F data=@invoice.json https://api.invopop.com/silo/v1/entries | jq .

The response back from the server will be similar to the following:

{
  "id": "0192b4f4-3eb6-74eb-b201-0954f12dbcb2",
  "created_at": "2024-10-22T15:59:18.738Z",
  "updated_at": "2024-10-22T15:59:18.738Z",
  "folder": "invoices",
  "draft": true,
  "env_schema": "https://gobl.org/draft-0/envelope",
  "doc_schema": "https://gobl.org/draft-0/bill/invoice",
  "digest": {
    "alg": "sha256",
    "val": "f5e1a5f81e9a0f42a6e666c6e6d33a1704331381d55190f7d6cab484b39c88e6"
  },
  "snippet": {
    "uuid": "0192b4f4-3ea5-71be-9323-2aea8c8bdadf",
    "type": "standard",
    "series": "TEST",
    "code": "",
    "currency": "GBP",
    "issue_date": "2024-10-22",
    "supplier": {
      "name": "BrightTech Solutions Ltd.",
      "country": "GB",
      "tax_code": "844281425"
    },
    "customer": {
      "name": "GreenWave Energy Ltd.",
      "country": "GB",
      "tax_code": "350983637"
    },
    "total": "800.00",
    "tax": "160.00",
    "total_with_tax": "960.00",
    "payable": "960.00"
  },
  "data": {
    "$schema": "https://gobl.org/draft-0/envelope",
    "head": {
      "uuid": "0192b4f4-3ea5-7012-9095-d7d55a90d7bf",
      "dig": {
        "alg": "sha256",
        "val": "f5e1a5f81e9a0f42a6e666c6e6d33a1704331381d55190f7d6cab484b39c88e6"
      }
    },
    "doc": {
      "$schema": "https://gobl.org/draft-0/bill/invoice",
      "$regime": "GB",
      "uuid": "0192b4f4-3ea5-71be-9323-2aea8c8bdadf",
      "type": "standard",
      "series": "TEST",
      "code": "",
      "issue_date": "2024-10-22",
      "currency": "GBP",
      "supplier": {
        "name": "BrightTech Solutions Ltd.",
        "tax_id": {
          "country": "GB",
          "code": "844281425"
        },
        "addresses": [
          {
            "num": "123",
            "street": "Innovation Park",
            "locality": "Cambridge",
            "code": "CB1 2AB",
            "country": "GB"
          }
        ],
        "emails": [
          {
            "addr": "billing@brighttech.co.uk"
          }
        ]
      },
      "customer": {
        "name": "GreenWave Energy Ltd.",
        "tax_id": {
          "country": "GB",
          "code": "350983637"
        },
        "addresses": [
          {
            "num": "45",
            "street": "Riverside Business Park",
            "locality": "London",
            "code": "SW1A 1AA",
            "country": "GB"
          }
        ],
        "emails": [
          {
            "addr": "info@greenwave.co.uk"
          }
        ]
      },
      "lines": [
        {
          "i": 1,
          "quantity": "50",
          "item": {
            "name": "Thermal efficient mugs",
            "price": "16.00"
          },
          "sum": "800.00",
          "taxes": [
            {
              "cat": "VAT",
              "rate": "standard",
              "percent": "20.0%"
            }
          ],
          "total": "800.00"
        }
      ],
      "totals": {
        "sum": "800.00",
        "total": "800.00",
        "taxes": {
          "categories": [
            {
              "code": "VAT",
              "rates": [
                {
                  "key": "standard",
                  "base": "800.00",
                  "percent": "20.0%",
                  "amount": "160.00"
                }
              ],
              "amount": "160.00"
            }
          ],
          "sum": "160.00"
        },
        "tax": "160.00",
        "total_with_tax": "960.00",
        "payable": "960.00"
      }
    }
  }
}

Let’s go over some of the important points in that response:

  • everything is wrapped inside a response containing the data and copies of key fields like the schemas, digest, and draft status,

  • we’ve created an entry in the silo. “Silo” is the name we gave to the place where you store your GOBL Envelopes,

  • there is an id or silo_entry_id property that uniquely identifies this entry in the silo,

  • the data property includes a complete GOBL Envelope with the invoice,

  • the invoice has now been completed with all the totals and tax calculations, and,

  • the invoice’s code field is still empty.

We don’t recommend making HTTP POST calls like in this example as they do not include an ID that would make the request idempotent. This is fine for testing, but in production environments, you should pre-assign a UUID (v1) to the request and include it in the path in a PUT call. This way, if for some reason the request gets repeated, you’ll only have one copy.

​
Create a Job

Now for the exciting part. But first, let’s recap what we have:

  • A workflow with a set of steps to execute, with an ID.

  • A silo entry ID generated in the last request when we uploaded the Invoice.

Let’s put all these together and execute a job. Here’s the command to perform from the terminal and don’t forget to update the IDs with your values that were generated for the workflow and silo entry:

curl -H "Authorization: Bearer $INVOPOP_TOKEN" -X POST -F workflow_id=0d9602ab-a2e2-413c-adf0-7abf4dd25c12 -F silo_entry_id=0192b4f4-3eb6-74eb-b201-0954f12dbcb2 "https://api.invopop.com/transform/v1/jobs?wait=30" | jq .

{
  "id": "0192b4f5-493d-7b23-a7aa-173354771ea5",
  "created_at": "2024-10-22T16:00:27.053Z",
  "updated_at": "2024-10-22T16:00:29.564Z",
  "silo_entry_id": "0192b4f4-3eb6-74eb-b201-0954f12dbcb2",
  "workflow_id": "03ae75a5-5dd9-486d-b389-ce9c9698be26",
  "status": "OK",
  "completed_at": "2024-10-22T16:00:29.564Z",
  "intents": [
    {
      "id": "0192b4f5-4a94-7c9f-87f1-738b4f9f800c",
      "created_at": "2024-10-22T16:00:27.284Z",
      "updated_at": "2024-10-22T16:00:27.738Z",
      "step_id": "f2e368c0-9083-11ef-a958-e7217a52d388",
      "name": "Add Sequential Code",
      "provider": "sequence.enumerate",
      "events": [
        {
          "index": 1,
          "status": "RUN",
          "at": "2024-10-22T16:00:27.332Z"
        },
        {
          "index": 2,
          "status": "OK",
          "at": "2024-10-22T16:00:27.738Z"
        }
      ],
      "completed": true
    },
    {
      "id": "0192b4f5-4cab-7def-8d84-7d022e8729a5",
      "created_at": "2024-10-22T16:00:27.819Z",
      "updated_at": "2024-10-22T16:00:28.854Z",
      "step_id": "fdad4000-9083-11ef-a958-e7217a52d388",
      "name": "Generate PDF",
      "provider": "pdf",
      "events": [
        {
          "index": 1,
          "status": "RUN",
          "at": "2024-10-22T16:00:27.959Z"
        },
        {
          "index": 2,
          "status": "OK",
          "at": "2024-10-22T16:00:28.854Z"
        }
      ],
      "completed": true
    },
    {
      "id": "0192b4f5-50e2-71c6-ada2-0aedffaa86ab",
      "created_at": "2024-10-22T16:00:28.898Z",
      "updated_at": "2024-10-22T16:00:29.551Z",
      "step_id": "01bf93f0-9084-11ef-a958-e7217a52d388",
      "name": "Send via Email",
      "provider": "email",
      "events": [
        {
          "index": 1,
          "status": "RUN",
          "at": "2024-10-22T16:00:28.944Z"
        },
        {
          "index": 2,
          "status": "OK",
          "at": "2024-10-22T16:00:29.551Z"
        }
      ],
      "completed": true
    }
  ],
  "envelope": {
    "$schema": "https://gobl.org/draft-0/envelope",
    "head": {
      "uuid": "0192b4f4-3ea5-7012-9095-d7d55a90d7bf",
      "dig": {
        "alg": "sha256",
        "val": "3ebefbc508c3f5281fd8a0d2833c15a820566e9292a70d78f9d21f0cbc923d7c"
      }
    },
    "doc": {
      "$schema": "https://gobl.org/draft-0/bill/invoice",
      "$regime": "GB",
      "uuid": "0192b4f4-3ea5-71be-9323-2aea8c8bdadf",
      "type": "standard",
      "series": "TEST",
      "code": "000001",
      "issue_date": "2024-10-22",
      "currency": "GBP",
      "supplier": {
        "name": "BrightTech Solutions Ltd.",
        "tax_id": {
          "country": "GB",
          "code": "844281425"
        },
        "addresses": [
          {
            "num": "123",
            "street": "Innovation Park",
            "locality": "Cambridge",
            "code": "CB1 2AB",
            "country": "GB"
          }
        ],
        "emails": [
          {
            "addr": "billing@brighttech.co.uk"
          }
        ]
      },
      "customer": {
        "name": "GreenWave Energy Ltd.",
        "tax_id": {
          "country": "GB",
          "code": "350983637"
        },
        "addresses": [
          {
            "num": "45",
            "street": "Riverside Business Park",
            "locality": "London",
            "code": "SW1A 1AA",
            "country": "GB"
          }
        ],
        "emails": [
          {
            "addr": "info@greenwave.co.uk"
          }
        ]
      },
      "lines": [
        {
          "i": 1,
          "quantity": "50",
          "item": {
            "name": "Thermal efficient mugs",
            "price": "16.00"
          },
          "sum": "800.00",
          "taxes": [
            {
              "cat": "VAT",
              "rate": "standard",
              "percent": "20.0%"
            }
          ],
          "total": "800.00"
        }
      ],
      "totals": {
        "sum": "800.00",
        "total": "800.00",
        "taxes": {
          "categories": [
            {
              "code": "VAT",
              "rates": [
                {
                  "key": "standard",
                  "base": "800.00",
                  "percent": "20.0%",
                  "amount": "160.00"
                }
              ],
              "amount": "160.00"
            }
          ],
          "sum": "160.00"
        },
        "tax": "160.00",
        "total_with_tax": "960.00",
        "payable": "960.00"
      }
    },
    "sigs": [
      "eyJhbGciOiJFUzI1NiIsImtpZCI6ImZjMmRlODVlLTUwMjAtNGZlNC04YWE0LTg1NTc2YTE2NWQ4OSJ9.eyJ1dWlkIjoiMDE5MmI0ZjQtM2VhNS03MDEyLTkwOTUtZDdkNTVhOTBkN2JmIiwiZGlnIjp7ImFsZyI6InNoYTI1NiIsInZhbCI6IjNlYmVmYmM1MDhjM2Y1MjgxZmQ4YTBkMjgzM2MxNWE4MjA1NjZlOTI5MmE3MGQ3OGY5ZDIxZjBjYmM5MjNkN2MifX0.frJtn7Y1IpEtzwmtKlHUwXEycZlZR1Vl1RQpXVfAhi0Qgdd9KBlA7xLsw2Nifx0XRNoqp_FZ5W6yKmdgB8IB9Q"
    ]
  },
  "attachments": [
    {
      "id": "0192b4f5-4f61-7573-994b-e9954b7c071d",
      "name": "TEST-000001.pdf",
      "hash": "02a661f17a918613a28231b7e6101e014c13e21a0641612e078773d4983ec0ba",
      "mime": "application/pdf",
      "size": 27870,
      "url": "https://silo.invopop.com/AZK09D62dOuyAQlU8S28sg/AZK09U9hdXOZS-mVS3wHHQ/TEST-000001.pdf?h=02a661f17a918613"
    }
  ]
}

There is a lot of JSON data there, but let’s break it down into the key bits of data:

  • Everything is wrapped inside a “Job” object with the key fields like workflow_id and silo_entry_id.

  • Job status shows OK indicating that this job has been completed successfully.

  • The intents list describes all the steps the job has gone through for each of the connectors defined in the workflow.

  • envelope contains a copy of the invoice we uploaded earlier except it has now been assigned a code and signed.

  • attachments includes a link to the PDF file that was generated.

​
Download the Results

Having completed a job, we can view the results in the Invopop Console or download the results directly based on the previous response. Take a look at the attachments attribute. Each attachment has a URL attribute that we can use to download the contents and then open the file:

curl "https://silo.invopop.com/AZK09D62dOuyAQlU8S28sg/AZK09U9hdXOZS-mVS3wHHQ/TEST-000001.pdf?h=02a661f17a918613" > invoice.pdf
open invoice.pdf

You can also download the attachment directly in your browser by copying and pasting the URL.

Authentication🇨🇴 Colombia