Invoice

API Endpoint	Namespace	Supported Generics
`invoice`	`evclient.invoice.<method>`	CRUD and RecycleBin

The isDraft attribute of invoices is of particular interest, as many modifications are not permitted by the API if isDraft = False. Also, the endpoint to create endpoints is pretty limited, you cannot pass invoice items or attachments when creating the invoice object. In general, you'll need to create the invoice in draft state first, perform the necessary modifications (like adding an attachment or adding items) and then remove the draft state.

Removing the draft state and PDF attachments

When removing the draft state (patch the invoice to set isDraft = False one of two things) can happen:

If you uploaded an attachment earlier, the invoice is simply created as is
If there's no attachment yet, and the invoice type is set appropriately, EasyVerein automatically generates a PDF invoice based on the settings you have configured.

Additional parameters¶

None

Generic Model Mappings¶

Generic Model	Invoice Model
`ModelType`	`Invoice`
`CreateModelType`	`InvoiceCreate`
`UpdateModelType`	`InvoiceUpdate`

Additional Methods¶

create_with_attachment ¶

create_with_attachment(invoice: InvoiceCreate, attachment: Path, set_draft_state: bool = True)

Creates an invoice with an attachment. Note that the only valid file type is PDF.

Note that this endpoint performs multiple API requests, depending on the final draft state. At least two requests are performed (create invoice draft and upload attachment). Then, if set_draft_state is set to True and the models attribute isDraft equals False, a third request is performed afterward to remove the draft state.

Parameters:

Name	Type	Description	Default
`invoice`	`InvoiceCreate`	The invoice object to be created	required
`attachment`	`Path`	The path to the attachment to be uploaded. Must be a PDF file and a `pathlib.Path` object	required
`set_draft_state`	`bool`	Whether to set the draft state of the invoice to `False` after uploading the attachment	`True`

create_with_items ¶

create_with_items(invoice: InvoiceCreate, items: List[InvoiceItemCreate], set_draft_state: bool = True)

The EV API doesn't support passing the InvoiceItems directly when creating an invoice, so this client exposes this helper method to simplify creation of invoices.

Note that this endpoint performs multiple API requests, depending on the number of items and the final draft state. At least, the invoice needs to be created in draft state. Then the items have to be added (one API request per item, as the API does not support a bulk create endpoint here). Finally, if set_draft_state is set to True and the models attribute isDraft equals False, a final request is performed afterward to remove the draft state.

PDF generation

Starting with the Hexa v1.7 API, the API will automatically generate a PDF attachment based on the provided data and the settings configured in the realm settings.

Parameters:

Name	Type	Description	Default
`invoice`	`InvoiceCreate`	Invoice to create	required
`items`	`List[InvoiceItemCreate]`	List of invoice items to add to the invoice	required
`set_draft_state`	`bool`	Whether to convert the invoice from draft state to an actual invoice after adding items	`True`

get_attachment ¶

get_attachment(invoice: Invoice | int) -> tuple[bytes, CaseInsensitiveDict[str]]

This method downloads and returns the invoice attachment if available.

It accepts either an invoice object or its id. If the invoice is given, and the path attribute is set, it will simply use this path to download and return the file. In all other cases, it first retrieves the invoice object by id and then proceeds to download the file.

Returns a tuple, where the first element is the file and the second contains the headers of the response

Usage

invoice = ev_connection.invoice.get_by_id(invoice_id, query="{id,path}")

attachment, headers = ev_connection.invoice.get_attachment(invoice)

Parameters:

Name	Type	Description	Default
`invoice`	`Invoice \| int`	The invoice object or its id for which the attachment should be retrieved	required

upload_attachment ¶

upload_attachment(invoice: Invoice | int, file: Path)

Uploads an attachment to an already existing invoice. The invoice must be in draft state, otherwise the upload will fail.

Parameters:

Name	Type	Description	Default
`invoice`	`Invoice \| int`	The invoice to upload the attachment to. Can be either an `Invoice` object or its ID	required
`file`	`Path`	The path to the attachment to be uploaded. Must be a PDF file and a `pathlib.Path` object	required