Invoices API

The Invoices API allows you to create, read, update, and delete invoices in your BillOver account.

Contents

• Base URL
• Field Definitions
• List Invoices
• Create Invoice
• Get Invoice
• Update Invoice
• Delete Invoice
• Approve Invoice
• Reject Invoice
• Remove Approval
• Export as CSV
• Export as Excel
• Error Responses
• Example Usage

Base URL

https://api.billover.com/v1/invoices/

Field Definitions

List Response Fields

Detail Response Fields (Additional)

Company Fields

Permission Fields

List Invoices

Retrieve a list of all invoices.

GET /v1/invoices/

Filter Parameters

Query Parameters

Sorting

List endpoint is sorted by creation date in descending order (-created_at) by default.

Response

{
    "count": 16,
    "page_count": 2,
    "page_size": 10,
    "results": [
        {
            "hf_id": "HPK",
            "uid": "67df8b92-ed61-4796-b5c2-9505bf9d4b6a",
            "total_price": "499.00",
            "total_price_display": "499.00",
            "currency": "EUR",
            "invoice_date": "2024-11-30",
            "company": {
                "uid": "fd0c0c55-ff4a-4efa-9cbc-43dab8470533",
                "name": "Sample Corporation Ltd.",
                "address": "123 Main Street, Anytown, USA 12345",
                "tax_number": null,
                "tax_office": null,
                "phone": null
            },
            "category": null,
            "processing_status": "finished",
            "approvement_status": "waiting",
            "permissions": {
                "can_update": true,
                "can_delete": true,
                "can_approve": true,
                "can_reject": true,
                "can_remove_approval": false
            },
            "created_at": "2024-11-30T21:02:29.706626+03:00",
            "workspace_user": {
                "uid": "211904c9-6a52-4d27-b800-ca98196d9144",
                "user": {
                    "uid": "a1b2c3d4-e5f6g7h8-i9j0k1l2m3",
                    "email": "[email protected]",
                    "first_name": "John",
                    "last_name": "Doe",
                    "full_name": "John Doe"
                },
                "role_type": "admin"
            }
        }
    ]
}

Create Invoice

Create a new invoice.

POST /v1/invoices/

Request Body

{
    "file": "binary_file_data"
}

Get Invoice

Retrieve a specific invoice by ID.

GET /v1/invoices/{uid}

Update Invoice

Update an existing invoice.

PUT /v1/invoices/{uid}

Request Body

{
    "total_price": "599.00",
    "total_vat": "107.82",
    "invoice_date": "2024-12-01",
    "invoice_number": "A-123",
    "currency": "TRY",
    "payment_type": "credit_card",
    "company_uid": "fd0c0c55-ba4f-4efa-9cbc-dd63b8470533",
    "card_uid": "67df8b92-ed61-4796-b5c2-9505bf9d4b6a"
}

Delete Invoice

Delete an invoice.

DELETE /v1/invoices/{uid}

Approve Invoice

Approve an invoice.

POST /v1/invoices/{uid}/approve

Response

{
    "uid": "67df8b92-ed61-4796-b5c2-9505bf9d4b6a",
    "approvement_status": "approved",
    "permissions": {
        "can_update": false,
        "can_delete": false,
        "can_approve": false,
        "can_reject": false,
        "can_remove_approval": true
    }
}

Reject Invoice

Reject an invoice.

POST /v1/invoices/{uid}/reject

Remove Approval

Remove approval status from an invoice.

POST /v1/invoices/{uid}/remove-approval

Export as CSV

Export invoices as CSV file.

POST /v1/invoices/export-csv

Export as Excel

Export invoices as Excel file.

POST /v1/invoices/export-xlsx

Error Responses

Example Usage

Create an Invoice

curl -X POST \
  https://api.billover.com/v1/invoices/ \
  -H 'Api-Key: YOUR_API_KEY' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@/path/to/invoice.pdf'

Response:

{
    "hf_id": "HPK",
    "uid": "67df8b92-ed61-4796-b5c2-9505bf9d4b6a",
    "file": "https://storage.billover.com/invoices/67df8b92-ed61-4796-b5c2-9505bf9d4b6a.pdf",
    "processing_status": "processing",
    "created_at": "2024-11-30T21:02:29.706626+03:00",
    "workspace_user": {
        "uid": "211904c9-6a52-4d27-b800-ca98196d9144",
        "user": {
            "uid": "03dc8842-f83d-4b55-806b-ad7a25e75600",
            "email": "[email protected]",
            "first_name": "John",
            "last_name": "Doe",
            "full_name": "John Doe"
        },
        "role_type": "admin"
    }
}

List Invoices with Filters

curl -X GET \
  'https://api.billover.com/v1/invoices/?company__uid=fd0c0c55-ba4f-4efa-9cbc-dd63b8470533&approvement_status=waiting' \
  -H 'Api-Key: YOUR_API_KEY'

Update an Invoice

curl -X PUT \
  https://api.billover.com/v1/invoices/67df8b92-ed61-4796-b5c2-9505bf9d4b6a \
  -H 'Api-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "total_price": "599.00",
    "total_vat": "107.82",
    "invoice_date": "2024-12-01",
    "invoice_number": "A-123",
    "currency": "TRY",
    "payment_type": "credit_card",
    "company_uid": "fd0c0c55-ba4f-4efa-9cbc-dd63b8470533",
    "card_uid": "67df8b92-ed61-4796-b5c2-9505bf9d4b6a"
}'

Approve an Invoice

curl -X POST \
  https://api.billover.com/v1/invoices/67df8b92-ed61-4796-b5c2-9505bf9d4b6a/approve \
  -H 'Api-Key: YOUR_API_KEY'

Export Invoices as CSV

curl -X POST \
  https://api.billover.com/v1/invoices/export-csv \
  -H 'Api-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

Export Invoices as Excel

curl -X POST \
  https://api.billover.com/v1/invoices/export-xlsx \
  -H 'Api-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'