Accounts Receivable

Business flow

Accounts Receivable (AR) covers the flow of issuing e-invoices from your business to your customers. With Staple, your accounting or ERP system does not need to integrate directly with each country’s tax authority or with the Peppol network — Staple handles all the country-specific format conversion, validation, and transport on your behalf.

One format, every country: STAR

Every country defines its own e-invoice format. Singapore uses Peppol UBL. Malaysia uses MyInvois UBL 2.1. India uses IRP JSON. Poland uses KSeF XML. Mexico uses CFDI XML. Each format has its own field names, structure, and validation rules. If your business operates in more than one country, integrating directly with each format multiplies the engineering work with every country added.

To remove this burden, Staple defines a single unified schema called STAR — Staple Transactional API Records. STAR is a country-agnostic representation of an invoice. You map your ERP data to STAR once, and Staple takes responsibility for converting STAR into the format each tax authority expects.

The full STAR schema reference is documented in Schema Objects.

How the AR flow works

The flow works as follows:

1. Your system produces a STAR invoice. Your accounting or ERP system constructs an invoice in STAR format using the data fields documented in the Schema Objects reference.
2. Submit the invoice to Staple. Your system calls the Submit endpoint with the STAR payload. Staple acknowledges receipt and queues the invoice for processing. The acknowledgement returns a docId you will use in subsequent steps.
3. Staple validates and clears the invoice. Behind the scenes, Staple performs two distinct steps:
   • Validation — Staple converts the STAR payload into the destination country’s e-invoice format and validates it against the schema and the relevant tax authority’s rules.
   • Clearance — Once validation passes, Staple submits the converted invoice to the tax authority portal or the Peppol network. The tax authority returns a clearance reference (such as a MyInvois UUID, SDI IdentificativoSdI, KSeF number, or IRN) that legally identifies the issued invoice.
4. Your system learns the outcome. You can learn the outcome in two ways:
   • Push — subscribe to webhook events and Staple notifies your server when each step completes.
   • Pull — call the Get invoice status endpoint at any time with the docId to retrieve the current validation status and clearance evidence.
5. Your buyer may accept, reject, or pay the invoice. Days or weeks later, the buyer at the receiving end may take action on the invoice you issued. If you want to be notified of buyer actions — particularly rejections — you can subscribe to the relevant webhook event.

Country support

Staple’s AR flow supports all 12 countries: 🇸🇬 Singapore · 🇨🇳 China · 🇲🇾 Malaysia · 🇵🇱 Poland · 🇫🇷 France · 🇧🇪 Belgium · 🇮🇹 Italy · 🇩🇪 Germany · 🇪🇸 Spain · 🇧🇷 Brazil · 🇲🇽 Mexico · 🇮🇳 India. Country-specific behaviour, required fields, and validation rules are documented inside each schema object and on the per-country payload pages.

Submit API

POST https://api.staple.io/v2/einvoice/submit/queue/:queueId

Submit a STAR e-invoice to Staple for conversion, validation, and submission to the destination country’s tax authority or the Peppol network. Compliance processing runs asynchronously — this endpoint acknowledges receipt of the payload and returns identifiers you can use to track the outcome.

1
POST https://api.staple.io/v2/einvoice/submit/queue/4173
2
Authorization: Bearer <token>
3
Content-Type: application/json
4
5
{
6
  "Country": "DE",
7
  "ComplianceStandards": ["eu-en16931-v2017", "de-xrechnung-v3"],
8
  "DocNumber": "INV-0001",
9
  "IssueDate": "2026-05-09",
10
  "Currency": "EUR",
11
  "Supplier": {
12
    "Name": "Mustermann GmbH",
13
    "TaxID": { "Country": "DE", "Code": "111111125" }
14
  },
15
  "Customer": {
16
    "Name": "Buyer GmbH",
17
    "TaxID": { "Country": "DE", "Code": "222222229" }
18
  },
19
  "Lines": [
20
    {
21
      "Quantity": "1.00",
22
      "Item": { "Name": "Consulting service", "Price": "1000.00" },
23
      "Taxes": [{ "Cat": "VAT", "Rate": "standard" }]
24
    }
25
  ]
26
}

The example above shows a minimum payload for Germany. The required fields and country-specific extensions differ for each supported country. See the Request Payloads section for the minimum payload example per country.

Response fields

After submission, validation and clearance run asynchronously. To learn the outcome, either subscribe to the webhook events described in Webhook notifications below, or pull the current status using the Get invoice status endpoint.

Get invoice status

GET https://api.staple.io/v1/documents/{identifier}

Retrieve the current validation and clearance status of an e-invoice you previously submitted. Use this endpoint when you need to check the outcome on demand — for example, when reconciling with your accounting system or troubleshooting a specific invoice.

The response is country-agnostic. Country-specific clearance evidence (such as MyInvois UUID, SDI IdentificativoSdI, or KSeF number) is returned inside the clearance block.

1
GET https://api.staple.io/v1/documents/9021
2
Authorization: Bearer <token>

validation block

The validation block describes whether the submitted invoice passed Staple’s internal validation and the tax authority’s schema-level rules.

clearance block

The clearance block describes whether the tax authority or the Peppol network has accepted the invoice and what evidence has been issued.

Search documents

POST https://api.staple.io/v2/search/documents

Search for e-invoices you have issued. Filter by Staple document ID, your own invoice number, tax authority reference, status, or date range. This endpoint returns a paginated list of summary results — for full validation and clearance details on a specific invoice, use the Get invoice status endpoint.

filter object fields

pagination object fields

1
POST https://api.staple.io/v2/search/documents
2
Authorization: Bearer <token>
3
Content-Type: application/json
4
5
{
6
  "filter": {
7
    "queue": [4173],
8
    "tab": ["COMPLETED"],
9
    "uploadedAt": {
10
      "from": "01/05/2026",
11
      "to": "31/05/2026"
12
    }
13
  },
14
  "pagination": {
15
    "skip": 0,
16
    "take": 50
17
  }
18
}

The underlying endpoint supports additional filters used elsewhere in the Staple platform (such as filename and content search) — those filters are omitted here as they are not commonly used in e-invoice workflows.

Webhook notifications

Subscribe to webhook events so your system is notified when Staple completes asynchronous processing of an e-invoice you submitted — without polling. Configure your webhook URL in User Profile → Webhooks. You will need the Manage webhooks permission to do this.

Three e-invoice events are available:

Webhook payload — document.validation_completed

1
{
2
  "event": "document.validation_completed",
3
  "payload": {
4
    "docId": 9021,
5
    "docNumber": "INV-0001",
6
    "country": "DE",
7
    "validation": {
8
      "status": "passed",
9
      "completedAt": "2026-05-09T09:18:42Z",
10
      "faults": []
11
    }
12
  }
13
}

When validation fails, the faults array contains the validation errors:

1
{
2
  "event": "document.validation_completed",
3
  "payload": {
4
    "docId": 9021,
5
    "docNumber": "INV-0001",
6
    "country": "DE",
7
    "validation": {
8
      "status": "failed",
9
      "completedAt": "2026-05-09T09:18:42Z",
10
      "faults": [
11
        "Tax code mismatch for line 1",
12
        "Missing buyer reference for DE XRechnung"
13
      ]
14
    }
15
  }
16
}

Webhook payload — document.cleared

1
{
2
  "event": "document.cleared",
3
  "payload": {
4
    "docId": 9021,
5
    "docNumber": "INV-0001",
6
    "country": "DE",
7
    "clearance": {
8
      "status": "cleared",
9
      "completedAt": "2026-05-09T09:21:00Z",
10
      "source": "tax_authority",
11
      "reference": "DE-XR-2026-AB12C345",
12
      "validationLink": "https://example-tax-authority/invoices/DE-XR-2026-AB12C345"
13
    }
14
  }
15
}

Webhook payload — document.rejected_by_buyer

1
{
2
  "event": "document.rejected_by_buyer",
3
  "payload": {
4
    "docId": 9021,
5
    "docNumber": "INV-0001",
6
    "country": "DE",
7
    "rejection": {
8
      "rejectedAt": "2026-05-12T14:05:00Z",
9
      "reasons": ["duplicate", "incorrect_amount"]
10
    }
11
  }
12
}