Invoices

Auth required: Yes (auth:api) for all endpoints.

---

Invoice Model Properties

The following properties apply to all invoice types (final, preprod, proforma).

Property	Type	Description
id	integer	Unique identifier
number	string	Invoice number (e.g. INV-2024-00001)
reference	string	Optional reference string
customer_id	integer	FK to customers
customer_file_id	integer	FK to customer files
date	date	Invoice date
batch	string	Billing batch identifier
services_start	date	Start of the service period covered
services_end	date	End of the service period covered
consumptions_start	date	Start of the consumption period
consumptions_end	date	End of the consumption period
total_without_tax	decimal	Total amount before tax
tax	decimal	Total tax amount
total_with_tax	decimal	Total amount including tax
tax_rates	text	JSON-encoded tax rate breakdown
credit	decimal	Credit applied to this invoice
net_to_pay	decimal	Net amount to pay after credit
automatic	boolean	Whether the invoice was generated automatically
file	boolean	Whether the PDF has been stored on disk
mail	boolean	Whether the invoice was sent by email
json	boolean	Whether the invoice was exported as JSON
is_canceled_by_invoice	integer	FK to the invoice that cancels this one (credit note relationship)
created_at	datetime	Creation timestamp
updated_at	datetime	Last update timestamp

Proforma-specific fields (for creation via POST /v1/invoices-proforma):

Property	Type	Required	Description
customer_id	integer	Yes	Customer to create the proforma for
payment_term	string	No	Payment term (used at publish time)
credit	decimal	No	Credit amount (used at publish time)
paymentMethod_id	integer	No	Payment method (used at publish time)
deposit_method	string	No	Deposit method (used at publish time)

Relations included in GET /v1/invoices/{id}:

• sales: array of sale line items (see Sales documentation)

---

Invoices (Final)

Base URL: /api/v1/invoices

Read-only via API. Invoices are generated from proforma invoices (see Proforma section).

GET /v1/invoices

List invoices for a customer.

Query parameters:

Parameter	Type	Required	Description
customer_id	integer	Yes	Filter by customer ID

Response 200: Array of invoice objects (invoice_light_resource collection).

Examples:

curl -X GET "https://your-instance.bluerocktel.net/api/v1/invoices?customer_id=42" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

import requests

response = requests.get(
    "https://your-instance.bluerocktel.net/api/v1/invoices",
    params={"customer_id": 42},
    headers={"Authorization": "Bearer YOUR_API_TOKEN"}
)
invoices = response.json()

$response = Http::withToken('YOUR_API_TOKEN')
    ->get('https://your-instance.bluerocktel.net/api/v1/invoices', [
        'customer_id' => 42,
    ]);

$invoices = $response->json();

const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/invoices?customer_id=42",
  {
    headers: {
      "Authorization": "Bearer YOUR_API_TOKEN",
      "Accept": "application/json"
    }
  }
);
const invoices = await response.json();

---

GET /v1/invoices/{id}

Get a single invoice with its sales relation.

URL parameters:

Parameter	Type	Description
id	integer	Invoice ID

Response 200: Invoice object. Response 404: Not found.

---

GET /v1/invoices/{id}/content

Get the invoice PDF document.

URL parameters:

Parameter	Type	Description
id	integer	Invoice ID

Response 200: PDF file (Content-Type: application/pdf). Response 404: PDF not found.

The PDF is either:

• Generated dynamically (if payer exists or legacy conditions apply), or
• Retrieved from OVH Swift object storage.

Examples:

curl -X GET "https://your-instance.bluerocktel.net/api/v1/invoices/123/content" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -o invoice_123.pdf

import requests

response = requests.get(
    "https://your-instance.bluerocktel.net/api/v1/invoices/123/content",
    headers={"Authorization": "Bearer YOUR_API_TOKEN"}
)

with open("invoice_123.pdf", "wb") as f:
    f.write(response.content)

$response = Http::withToken('YOUR_API_TOKEN')
    ->get('https://your-instance.bluerocktel.net/api/v1/invoices/123/content');

Storage::put('invoice_123.pdf', $response->body());

const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/invoices/123/content",
  {
    headers: { "Authorization": "Bearer YOUR_API_TOKEN" }
  }
);
const blob = await response.blob();

---

Invoices Preprod

Base URL: /api/v1/invoices-preprod

Read-only. Pre-production invoice previews for billing review.

GET /v1/invoices-preprod

List preprod invoices. (Same interface as invoices.)

Query parameters:

Parameter	Type	Required	Description
customer_id	integer	Yes	Filter by customer ID

Response 200: Array of preprod invoice objects.

---

GET /v1/invoices-preprod/{id}

Get a single preprod invoice.

Response 200: Preprod invoice object.

---

GET /v1/invoices-preprod/{id}/content

Get the preprod invoice as a PDF (dynamically generated).

Response 200: PDF file (Content-Type: application/pdf).

---

Proforma Invoices

Base URL: /api/v1/invoices-proforma

Proforma invoices are draft invoices. They can be published (converted to real invoices).

GET /v1/invoices-proforma

List proforma invoices for a customer.

Query parameters:

Parameter	Type	Required	Description
customer_id	integer	Yes	Filter by customer ID

Response 200: Array of proforma invoice objects.

---

POST /v1/invoices-proforma

Create a new proforma invoice. Defaults: total_without_tax: 0, tax: 0, total_with_tax: 0, credit: 0, net_to_pay: 0, automatic: false, date: now.

Query parameters:

Parameter	Type	Required	Description
customer_id	integer	Yes	Customer to create proforma for

Response 201: Created proforma invoice object.

Examples:

curl -X POST "https://your-instance.bluerocktel.net/api/v1/invoices-proforma?customer_id=42" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

import requests

response = requests.post(
    "https://your-instance.bluerocktel.net/api/v1/invoices-proforma",
    params={"customer_id": 42},
    headers={"Authorization": "Bearer YOUR_API_TOKEN"}
)
proforma = response.json()

$response = Http::withToken('YOUR_API_TOKEN')
    ->post('https://your-instance.bluerocktel.net/api/v1/invoices-proforma', [
        'customer_id' => 42,
    ]);

$proforma = $response->json();

const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/invoices-proforma?customer_id=42",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_TOKEN",
      "Accept": "application/json"
    }
  }
);
const proforma = await response.json();

---

GET /v1/invoices-proforma/{id}

Get a single proforma invoice with its sales relation.

Response 200: Proforma invoice object.

---

GET /v1/invoices-proforma/{id}/content

Get the proforma invoice as a PDF (dynamically generated).

Response 200: PDF file (Content-Type: application/pdf).

---

DELETE /v1/invoices-proforma/{id}

Delete a proforma invoice.

Response 200: Success message. Response 404: Not found.

---

POST /v1/invoices-proforma/{id}/publish

Publish a proforma invoice: converts it to a real invoice via the publish_proforma_invoice action.

URL parameters:

Parameter	Type	Description
id	integer	Proforma invoice ID

Body (JSON): Validated via invoice_proforma::attributes('publish'):

Field	Type	Description
payment_term	string	Payment term
credit	numeric	Credit amount
paymentMethod_id	integer	Payment method ID
deposit_method	string	Deposit method

Response 201: Published invoice object. Response 422: Validation error.

Examples:

curl -X POST "https://your-instance.bluerocktel.net/api/v1/invoices-proforma/15/publish" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_term": "30_days",
    "credit": 0,
    "paymentMethod_id": 1,
    "deposit_method": "direct_debit":
  }'

import requests

response = requests.post(
    "https://your-instance.bluerocktel.net/api/v1/invoices-proforma/15/publish",
    headers={"Authorization": "Bearer YOUR_API_TOKEN"},
    json={
        "payment_term": "30_days",
        "credit": 0,
        "paymentMethod_id": 1,
        "deposit_method": "direct_debit":
    }
)
invoice = response.json()

$response = Http::withToken('YOUR_API_TOKEN')
    ->post('https://your-instance.bluerocktel.net/api/v1/invoices-proforma/15/publish', [
        'payment_term' => '30_days',
        'credit' => 0,
        'paymentMethod_id' => 1,
        'deposit_method' => 'direct_debit',
    ]);

$invoice = $response->json();

const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/invoices-proforma/15/publish",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_TOKEN",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      payment_term: "30_days",
      credit: 0,
      paymentMethod_id: 1,
      deposit_method: "direct_debit":
    })
  }
);
const invoice = await response.json();