GetbeelDocs

Move a filing in the commercialista review

approved (visto bueno: approved_at, approved_by), changes_requested (reason required; only the commercialista, who reviews in the app), skipped (not to be done: reason required; never prepared automatically again, never charged), needs_review (back to review, or reopen a skipped filing: one skipped before it was prepared goes back to to_prepare), filed (a LIPE, annual VAT return or Redditi PF return sent: reference = its protocol number). When the team requires the commercialista's approval (tax settings require_accountant_approval), an API key cannot approve and a receipt waits for the approval (409 approval_required). Every change goes in the history (/filings/{id}/events), the audit log and webhooks filing.needs_review, filing.changes_requested, filing.approved, filing.skipped and filing.filed. Pay as you go: filed completes the filing and charges it once from the prepaid balance, with the same charge as its receipt (never twice); approving, changes_requested, skipping and reopening are free. Live keys only.

POST
/filings/{id}/status

approved (visto bueno: approved_at, approved_by), changes_requested (reason required; only the commercialista, who reviews in the app), skipped (not to be done: reason required; never prepared automatically again, never charged), needs_review (back to review, or reopen a skipped filing: one skipped before it was prepared goes back to to_prepare), filed (a LIPE, annual VAT return or Redditi PF return sent: reference = its protocol number). When the team requires the commercialista's approval (tax settings require_accountant_approval), an API key cannot approve and a receipt waits for the approval (409 approval_required). Every change goes in the history (/filings/{id}/events), the audit log and webhooks filing.needs_review, filing.changes_requested, filing.approved, filing.skipped and filing.filed. Pay as you go: filed completes the filing and charges it once from the prepaid balance, with the same charge as its receipt (never twice); approving, changes_requested, skipping and reopening are free. Live keys only.

Autorizzazione

apiKey
headerAuthorizationBearer <token>

API key: gb_test_… or gb_live_…

id*string
Getbeel-Company?string

Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.

Formatuuid
application/json
  1. body
status*string

approved (visto bueno), changes_requested (reason required; the commercialista only), skipped (reason required), needs_review (back to review, or reopen a skipped filing), filed (a LIPE or VAT return, with reference)

Value in"needs_review""changes_requested""approved""skipped""filed"
reason?|

Why: required for changes_requested and skipped

reference?|

filed only: the protocol number of the sent return

expected_updated_at?|

The filing's updated_at as you last read it. When set and the filing changed since (recomputed or reviewed by someone else), the call fails with 409 filing_changed, so an approval never applies to figures you did not see

Corpo della risposta

OK

application/json
  1. response

The filing after the change, or FilingReopened when a filing skipped before it was prepared is reopened

id*string
object*string
type*string
Value in"bollo""withholdings""vat_payment""lipe""vat_return""redditi_pf"
period*string
status*string

ready: prepared, no review asked; needs_review: waiting for the commercialista; changes_requested: sent back (see the history); approved: visto bueno (approved_at, approved_by); skipped: not to be done (skip_reason); filed: return sent (receipt or filed_reference); paid: F24 paid (receipt)

Value in"ready""needs_review""changes_requested""approved""skipped""filed""paid"
approved_at*|null
approved_by*|

User id of who approved it

skip_reason*string|null
filed_reference*|

Protocol number of a filed return (evidence without a file)

extension*|

Set when a published extension (proroga) gave the due date: the official source

file_spec*|

The official specification the filing file follows, stored when the filing was prepared (also in the Getbeel-File-Spec header of the file). null: no file (skipped before it was prepared)

due_date*string
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
amount*string

Decimal amount as a string

Match^-?\d+\.\d{2}$
currency*string
f24_lines*array<>
details*
checks*

Checks getbeel ran on the file

needs_review*boolean
receipt*|null
completed_at*|null
created_at*string
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])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
Formatdate-time
updated_at*string
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])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
Formatdate-time
next_steps*
Esempio di richiesta
curl -X POST 'https://www.getbeel.com/api/v1/filings/string/status' \  -H 'Content-Type: application/json' \  -d '{  "status": "needs_review"}'
Esempio di risposta
{  "id": "fil_3f2a…",  "object": "filing",  "type": "bollo",  "period": "string",  "status": "ready",  "approved_at": "2019-08-24T14:15:22Z",  "approved_by": "string",  "skip_reason": "string",  "filed_reference": "string",  "extension": {    "source_title": "string",    "source_url": "string"  },  "file_spec": {    "id": "lipe:IVP18",    "file": "lipe_xml",    "name": "string",    "version": "IVP18 (schema Versione 1.0)",    "approved_by": "Provv. AdE prot. 125654 of 14 March 2024",    "source_url": "string",    "official_format": true,    "tax_year": -9007199254740991,    "other_tax_year": true,    "provisional": true  },  "due_date": "2026-10-29",  "amount": "122.00",  "currency": "EUR",  "f24_lines": [    {      "section": "erario",      "tax_code": "2523",      "reference_month": "string",      "reference_year": "2026",      "amount": "122.00"    }  ],  "details": {    "invoices": [      {        "id": "string",        "number": "string",        "date": "2026-10-29",        "list": "A"      }    ],    "pending_invoices": [      {        "id": "string",        "number": "string",        "date": "2026-10-29"      }    ],    "invoices_without_bollo_flag": -9007199254740991,    "bollo_threshold_confirmed": true,    "deferral": {      "pay_by": "september_30"    },    "settlement": {      "id": "string",      "lipe": {        "operations_active": "122.00",        "operations_passive": "122.00",        "vat_due": "122.00",        "vat_deducted": "122.00",        "vat_balance_debit": "122.00",        "vat_balance_credit": "122.00",        "previous_debt": "122.00",        "previous_credit": "122.00",        "annual_credit": "122.00",        "car_payments": "122.00",        "tax_credits": "122.00",        "interest": "122.00",        "advance": "122.00",        "advance_method": -9007199254740991,        "amount_due": "122.00",        "amount_credit": "122.00"      },      "notes": [        "string"      ]    },    "lipe": {      "year": -9007199254740991,      "quarter": -9007199254740991,      "declarant": {        "fiscal_code": "string",        "role": -9007199254740991      },      "modules": [        {          "month": -9007199254740991,          "quarter": -9007199254740991,          "lipe": {            "operations_active": "122.00",            "operations_passive": "122.00",            "vat_due": "122.00",            "vat_deducted": "122.00",            "vat_balance_debit": "122.00",            "vat_balance_credit": "122.00",            "previous_debt": "122.00",            "previous_credit": "122.00",            "annual_credit": "122.00",            "car_payments": "122.00",            "tax_credits": "122.00",            "interest": "122.00",            "advance": "122.00",            "advance_method": -9007199254740991,            "amount_due": "122.00",            "amount_credit": "122.00"          }        }      ]    },    "vat_return": {      "year": -9007199254740991,      "model": {        "name": "IVA 2026",        "tax_year": -9007199254740991,        "approved_by": "string",        "instructions_url": "string",        "technical_specs": "string"      },      "lines": [        {          "quadro": "VE",          "row": "VE23",          "field": -9007199254740991,          "code": "VE023001",          "label": "string",          "amount": -9007199254740991        }      ],      "balance": {        "to_pay": -9007199254740991,        "credit": -9007199254740991,        "tax_code": "6099"      },      "volume_d_affari": -9007199254740991,      "periods": [        {          "period": "string",          "settlement_saved": true,          "amount_to_pay": 0,          "advance": 0,          "paid": 0        }      ],      "issues": [        {          "code": "string",          "message": "string",          "items": [            "string"          ],          "taxable": 0,          "vat": 0        }      ],      "checks": [        {          "rule": "string",          "ok": true        }      ]    },    "redditi_pf": {      "year": -9007199254740991,      "entity": "forfettario",      "model": "Redditi PF 2026",      "lines": [        {          "quadro": "LM",          "rigo": "string",          "key": "string",          "label": "string",          "amount": "122.00"        }      ],      "payments": [        {          "property1": null,          "property2": null        }      ],      "balance_to_pay": 0,      "warnings": [        "string"      ],      "needs_review": true    },    "withholdings": [      {        "id": "string",        "recipient_name": "string",        "document_number": "string",        "paid_on": "2026-10-29",        "withheld_amount": "122.00"      }    ]  },  "checks": {    "xsd": {      "schema": "string",      "valid": true,      "issues": [        {          "message": "string",          "line": -9007199254740991        }      ]    },    "ade_control_software": "not_run"  },  "needs_review": true,  "receipt": {    "uploaded_at": "2019-08-24T14:15:22Z"  },  "completed_at": "2019-08-24T14:15:22Z",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z",  "next_steps": {    "file_url": "string",    "deep_link": {      "url": "string",      "label": "string"    },    "other_links": [      {        "url": "string",        "label": "string"      }    ],    "copy_values": [      {        "key": "string",        "label": "string",        "value": "string"      }    ],    "drafts": [      {        "id": "bank",        "subject": "string",        "body": "string"      }    ],    "steps": [      "string"    ]  }}