# Tutorial: Receiving Invoices

This page describes the steps necessary to receive invoices using the PurchaseInvoice endpoint.

ReceiveInvoiceDiagram

# Step 1: Subscribe and Listen to the webhook

In order to receive a document, you'll need to subscribe to the "InvoiceReceived" webhook. For this example, we are going to use a mailhook. Use the PUT hook API call as shown below. In topics you can specify for which events you wish to receive a webhook.

WebhookParameters

Example body:

{
  "id": "1",
  "name": "mail hook",
  "action": "mailto:example@econnect.eu",
  "topics": [
    "InvoiceReceived",
    "InvoiceReceivedError",
    "InvoiceSent",
    "InvoiceSentError",
    "InvoiceSentRetry",
    "HookSent",
    "HookSentError",
    "HookSentRetry"
  ],
  "isActive": true,
  "createdOn": "0001-01-01T00:00:00+00:00",
  "changedOn": null
}

If you want to use a webhook instead, you can use something like "action": "https://user:pass@webhook.site/a81a0be5-8aad-4110-a40c-aa41a2c6e9ac#secureKey" instead. More information regarding webhooks can be found on the hooks page

# Step 2: Ping

An easy way to test the 'InvoiceReceived' hook is to use GET /api/v1/{partyId}/hook/ping. Calling this endpoint will send a dummy invoice to the specified partyId and trigger the 'InvoiceReceived' hook.

# Step 3: Download the invoice

We are going to use the mailhook for now. When you receive an invoice, you should receive something like the text below in your email inbox from noreply@everbinding.nl.

InvoiceReceived for NL:KVK:12345678
Message: 'Invoice' received.
DocumentId: 0d0167cb-72f1-4656-801b-17ff3a6ddb59
NotificationId: 2c25778f-2560-49bf-aac2-882c6fcb2fc4
EventId: 56b97522-7e9e-45d6-9b98-43634ee06a9b

With the DocumentId you got from the mailhook, call the purchaceInvoice/download API. Let's use the DocumentId and our partyId to download our invoice.

DownloadParameters

In the response you'll find the invoice document:

<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2&#xD;&#xA;                http://docs.oasis-open.org/ubl/os-UBL-2.1/xsd/maindoc/UBL-Invoice-2.1.xsd">
  <cbc:UBLVersionID>2.1</cbc:UBLVersionID>
  <cbc:CustomizationID>urn:www.cenbii.eu:transaction:biitrns010:ver2.0:extended:urn:www.peppol.eu:bis:peppol4a:ver2.0:extended:urn:www.simplerinvoicing.org:si:si-ubl:ver1.2</cbc:CustomizationID>
  <cbc:ProfileID>urn:www.cenbii.eu:profile:bii04:ver1.0</cbc:ProfileID>
  <cbc:ID>APAAS SwaggerTest</cbc:ID>
  <cbc:IssueDate>2013-08-06</cbc:IssueDate>
  <cbc:InvoiceTypeCode listID="UNCL1001" listAgencyID="6">380</cbc:InvoiceTypeCode>
  <cbc:DocumentCurrencyCode listID="ISO4217" listAgencyID="6">EUR</cbc:DocumentCurrencyCode>
  <cac:AccountingSupplierParty>
    <cac:Party>
      <cac:PartyName>
        <cbc:Name>Seller B.V.</cbc:Name>
      </cac:PartyName>
      <cac:PostalAddress>
        <cbc:StreetName>Main street</cbc:StreetName>
        <cbc:CityName>Big city</cbc:CityName>
        <cbc:PostalZone>54321</cbc:PostalZone>
        <cac:Country>
          <cbc:IdentificationCode listAgencyID="6" listID="ISO3166-1:Alpha2">NL</cbc:IdentificationCode>
        </cac:Country>
      </cac:PostalAddress>
      <cac:PartyLegalEntity>
        <cbc:CompanyID schemeID="NL:KVK">12345678</cbc:CompanyID>
      </cac:PartyLegalEntity>
      <cac:Contact>
        <cbc:ElectronicMail>email@example.com</cbc:ElectronicMail>
      </cac:Contact>
    </cac:Party>
  </cac:AccountingSupplierParty>
  <cac:AccountingCustomerParty>
    <cac:Party>
      <cac:PartyName>
        <cbc:Name>Buyercompany VOF</cbc:Name>
      </cac:PartyName>
      <cac:PostalAddress>
        <cbc:StreetName>Main street</cbc:StreetName>
        <cbc:CityName>Big city</cbc:CityName>
        <cbc:PostalZone>54321</cbc:PostalZone>
        <cac:Country>
          <cbc:IdentificationCode listAgencyID="6" listID="ISO3166-1:Alpha2">NL</cbc:IdentificationCode>
        </cac:Country>
      </cac:PostalAddress>
      <cac:PartyLegalEntity>
        <cbc:CompanyID schemeID="NL:KVK">12345678</cbc:CompanyID>
      </cac:PartyLegalEntity>
    </cac:Party>
  </cac:AccountingCustomerParty>
  <cac:LegalMonetaryTotal>
    <cbc:LineExtensionAmount currencyID="EUR">200</cbc:LineExtensionAmount>
    <cbc:TaxExclusiveAmount currencyID="EUR">200</cbc:TaxExclusiveAmount>
    <cbc:TaxInclusiveAmount currencyID="EUR">200</cbc:TaxInclusiveAmount>
    <cbc:PayableAmount currencyID="EUR">200</cbc:PayableAmount>
  </cac:LegalMonetaryTotal>
  <cac:InvoiceLine>
    <cbc:ID>1</cbc:ID>
    <cbc:InvoicedQuantity unitCode="59" unitCodeListID="UNECERec20">1</cbc:InvoicedQuantity>
    <cbc:LineExtensionAmount currencyID="EUR">200</cbc:LineExtensionAmount>
    <cac:Item>
      <cbc:Name>Bitcoin Masterclass</cbc:Name>
    </cac:Item>
    <cac:Price>
      <cbc:PriceAmount currencyID="EUR">200</cbc:PriceAmount>
    </cac:Price>
  </cac:InvoiceLine>
</Invoice>
© 2021 eConnect International B.V.