Billing API - Documentation

1. Endpoint Contract

This endpoint is synchronous: each request returns either a final issuance result or a final error.

Method: POST
Path: /api/v1/invoices/
Content-Type: application/json

2. Authentication

2.1 Required headers

X-Client-Id
X-Api-Key
X-Api-Secret
Idempotency-Key (required)

The credentials below are for demonstration only and do not grant real access.

X-Client-Id: airtable_ops_prod
X-Api-Key: ak_demo_9f83b7d1a5c40c22
X-Api-Secret: as_demo_5baf4f0f613949f0863b83de8f4c4f90

3. JSON Payload

Optional fields can be omitted. If VAT number is missing, the system applies final-consumer VAT number internally.

{
  "reference": "TI-2026-05-18-0007",
  "customer": {
    "name": "Eduardo Costa",
    "vat_number": "509999999",
    "email": "[email protected]",
    "address": "Rua do Campo Grande 45, Lisboa"
  },
  "items": [
    {
      "product": "mensalidade TheInventors",
      "gross_price": 10.00,
      "vat_rate": 23
    }
  ]
}

Relevant rules

reference, customer.name, and items are required.
items[].vat_rate accepts a numeric VAT percentage (for example 23, 13, 6, 16).
Net price is calculated internally from gross_price for Moloni issuance.
Legacy PT payload keys and legacy VAT code strings are still accepted for backward compatibility.

Optional fields (accepted and processed)

Field	Type	Behavior
customer.vat_number	string	If present, validated as PT VAT number (9 digits + checksum). If omitted, final-consumer VAT number is used.
customer.address	string	If present, forwarded to customer create/update flow in Moloni.
customer.email	string	If present, validated as email and forwarded to customer flow in Moloni.

4. cURL Example (realistic request)

#!/usr/bin/env bash
set -euo pipefail

PATH_URL="/api/v1/invoices/"
BASE_URL="https://billing.theinventors.io"
IDEMP="2878e76a-6654-4e52-a11b-dcc525eef985"
CLIENT_ID="airtable_ops_prod"
API_KEY="ak_demo_9f83b7d1a5c40c22"
API_SECRET="as_demo_5baf4f0f613949f0863b83de8f4c4f90"

BODY='{"reference":"TI-2026-05-18-0007","customer":{"name":"Eduardo Costa","email":"[email protected]","address":"Rua do Campo Grande 45, Lisboa"},"items":[{"product":"mensalidade TheInventors","gross_price":10.00,"vat_rate":23}]}'

curl -sS -X POST "${BASE_URL}${PATH_URL}" \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: ${CLIENT_ID}" \
  -H "X-Api-Key: ${API_KEY}" \
  -H "X-Api-Secret: ${API_SECRET}" \
  -H "Idempotency-Key: ${IDEMP}" \
  --data "$BODY"

5. Success Response

{
  "success": true,
  "request_id": "req_4ad9b2ec1d9f3a71",
  "reference": "TI-2026-05-18-0007",
  "document": {
    "type": "invoice_receipt",
    "moloni_document_id": 974989624,
    "number": "FR M/32",
    "series": "M",
    "total_gross": 10,
    "currency": "EUR",
    "pdf_url": "https://...",
    "created_at": "2026-05-18T15:07:21Z"
  }
}

6. Error Response

{
  "success": false,
  "request_id": "req_62d03a9dabc7e8f4",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "items[0].vat_rate is invalid.",
    "details": null
  }
}

7. HTTP and Functional Codes

HTTP	Code	When it happens
201	—	Document issued successfully.
400	VALIDATION_ERROR	Invalid payload or missing Idempotency-Key.
401	AUTH_ERROR	Invalid credentials, signature, timestamp, or nonce.
403	IP_NOT_ALLOWED	Source IP is outside the key whitelist.
409	IDEMPOTENCY_CONFLICT	Same Idempotency-Key used with a different body.
422	MOLONI_BUSINESS_ERROR	Business rule rejected by Moloni API.
422	CUSTOMER_AMBIGUOUS	Ambiguous customer during resolution process.
502	MOLONI_BAD_GATEWAY	Invalid/intermediary response from Moloni.
503	MOLONI_UNAVAILABLE	Moloni service unavailable.
504	MOLONI_TIMEOUT	Timeout while communicating with Moloni.

8. Integration Notes

Reuse the same Idempotency-Key only when retrying the same logical request.
Always send a unique Idempotency-Key per logical request.
Always use HTTPS and never log api_secret.
Invoice email sender (planned): [email protected].

Backoffice: https://billing.theinventors.io/admin/