GetbeelDocs

Draft of the quarterly OSS return

For a company registered in the OSS union scheme: per Member State of the consumer, the taxable amount and the VAT of the quarter from the issued invoices with Natura N7 to EU consumers, at each State's standard rate on the invoice date (VAT rounded per line, then added up; vat_country_level shows the per-country computation, rounding_gap when they differ by more than €0.01). Credit notes on earlier quarters are corrections; a State's negative balance is refunded, never offset. doubtful lists the invoices that need a decision (reason). deadline is the nominal date, never moved; reference is the payment reference. Free and read-only: the return is entered and paid in the AdE Portale OSS with the company's own credentials, never with F24. reliable is always false (reduced rates and goods are not modelled).

GET
/companies/me/oss-return

For a company registered in the OSS union scheme: per Member State of the consumer, the taxable amount and the VAT of the quarter from the issued invoices with Natura N7 to EU consumers, at each State's standard rate on the invoice date (VAT rounded per line, then added up; vat_country_level shows the per-country computation, rounding_gap when they differ by more than €0.01). Credit notes on earlier quarters are corrections; a State's negative balance is refunded, never offset. doubtful lists the invoices that need a decision (reason). deadline is the nominal date, never moved; reference is the payment reference. Free and read-only: the return is entered and paid in the AdE Portale OSS with the company's own credentials, never with F24. reliable is always false (reduced rates and goods are not modelled).

Autorizzazione

apiKey
headerAuthorizationBearer <token>

API key: gb_test_… or gb_live_…

Parametri query

period*string

A quarter (2026-Q3): the OSS return is quarterly

Match^\d{4}-Q[1-4]$

Corpo della risposta

OK

application/json
  1. response
object*string
period*string
registered*boolean

Registered in the OSS union scheme (tax settings oss_from / oss_until) for some day of the quarter

registration*
deadline*string

Last day of the month after the quarter. Not moved for weekends or holidays: verify any extension (proroga)

Match^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
Formatdate
reference*|

The payment reference IT/IT{partita IVA}/Q{n}.{YYYY} (null without a valid partita IVA)

currency*string
countries*array<>
corrections*array<>
balances*array<>
total_due*string

VAT to pay: positive balances only; a State's negative balance is refunded by that State

Match^-?\d+\.\d{2}$
refunds*array<>
nil_return*boolean

Nothing to declare: a nil return is still due

doubtful*array<>
reliable*boolean
Esempio di richiesta
curl -X GET 'https://www.getbeel.com/api/v1/companies/me/oss-return?period=string'
Esempio di risposta
{  "object": "oss_return_draft",  "period": "2026-Q3",  "registered": true,  "registration": {    "from": "2026-10-29",    "until": "2026-10-29"  },  "deadline": "2026-10-29",  "reference": "IT/IT01234567897/Q3.2026",  "currency": "EUR",  "countries": [    {      "country": "string",      "rate": 0,      "supply": "services",      "taxable": "122.00",      "vat": "122.00",      "vat_country_level": "122.00",      "rounding_gap": true,      "invoices": -9007199254740991    }  ],  "corrections": [    {      "period": "string",      "country": "string",      "vat": "122.00"    }  ],  "balances": [    {      "country": "string",      "vat": "122.00"    }  ],  "total_due": "122.00",  "refunds": [    {      "country": "string",      "vat": "122.00"    }  ],  "nil_return": true,  "doubtful": [    {      "invoice_id": "string",      "number": "string",      "date": "2026-10-29",      "reason": "n7_not_eu_consumer",      "country": "string"    }  ],  "reliable": false}