Skip to main content
The Invoices API enables you to create and retrieve electronic invoices for customer orders. RestAI supports both boletas (simple receipts) and facturas (tax invoices) with automatic series numbering and tax calculations.

​
Features

  • Electronic Invoicing: Generate boletas and facturas with automatic numbering
  • Document Validation: Validate DNI, RUC, and CE document numbers
  • Tax Calculation: Automatic IGV (18%) calculation and subtotal breakdown
  • Series Management: Auto-incrementing series numbers per branch (B001 for boletas, F001 for facturas)
  • SUNAT Integration: Track SUNAT submission status

​
Authentication

Requires authentication and the following permissions:
  • invoices:read - View invoices
  • invoices:create - Create invoices

​
Base URL

https://api.restai.app/v1/invoices

​
Invoice Types

​
Boleta

Simple receipt for customers with DNI or CE. Uses series prefix B001.

​
Factura

Tax invoice for businesses. Requires RUC. Uses series prefix F001.

​
Document Types

  • dni - DNI (8 digits)
  • ruc - RUC (11 digits, must start with 10 or 20)
  • ce - Carnet de Extranjería (9-12 characters)

​
Create Invoice

Generate an invoice for an order with automatic tax calculation and series numbering.

​
Endpoint

POST /invoices

​
Request Body

​
orderId
string
required
UUID of the order to invoice
​
type
string
required
Invoice type: boleta or factura
​
customerName
string
required
Customer name (1-255 characters)
​
customerDocType
string
required
Document type: dni, ruc, or ce
​
customerDocNumber
string
required
Document number meeting validation rules:
  • DNI: exactly 8 digits
  • RUC: exactly 11 digits starting with 10 or 20
  • CE: 9-12 characters

​
Response

​
success
boolean
Whether invoice was created successfully
​
data
object
​
id
string
Invoice UUID
​
order_id
string
Order UUID
​
organization_id
string
Organization UUID
​
branch_id
string
Branch UUID
​
type
string
Invoice type (boleta or factura)
​
series
string
Invoice series (B001 or F001)
​
number
number
Sequential invoice number within the series
​
customer_name
string
Customer name
​
customer_doc_type
string
Document type
​
customer_doc_number
string
Document number
​
subtotal
number
Amount before tax (total / 1.18)
​
igv
number
IGV tax amount (18%)
​
total
number
Total amount including tax
​
sunat_status
string
SUNAT submission status (default: “pending”)
​
created_at
string
Creation timestamp

​
Example Request

curl -X POST https://api.restai.app/v1/invoices \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "550e8400-e29b-41d4-a716-446655440000",
    "type": "boleta",
    "customerName": "Juan Perez",
    "customerDocType": "dni",
    "customerDocNumber": "12345678"
  }'

​
Example Response

{
  "success": true,
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440000",
    "order_id": "550e8400-e29b-41d4-a716-446655440000",
    "organization_id": "880e8400-e29b-41d4-a716-446655440000",
    "branch_id": "990e8400-e29b-41d4-a716-446655440000",
    "type": "boleta",
    "series": "B001",
    "number": 42,
    "customer_name": "Juan Perez",
    "customer_doc_type": "dni",
    "customer_doc_number": "12345678",
    "subtotal": 4237,
    "igv": 763,
    "total": 5000,
    "sunat_status": "pending",
    "created_at": "2026-03-02T10:30:00Z"
  }
}

​
List Invoices

Retrieve invoices for the current branch with optional filtering.

​
Endpoint

GET /invoices

​
Query Parameters

​
type
string
Filter by invoice type: boleta or factura
​
startDate
string
Filter invoices created after this ISO 8601 date
​
endDate
string
Filter invoices created before this ISO 8601 date

​
Response

Returns up to 100 invoices ordered by creation date (newest first).

​
Example Request

curl https://api.restai.app/v1/invoices?type=factura&startDate=2026-03-01 \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Get Invoice Details

Retrieve a specific invoice by ID.

​
Endpoint

GET /invoices/:id

​
Path Parameters

​
id
string
required
Invoice UUID

​
Example Request

curl https://api.restai.app/v1/invoices/770e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Validation Rules

​
DNI Validation

  • Must be exactly 8 digits
  • All numeric characters

​
RUC Validation

  • Must be exactly 11 digits
  • All numeric characters
  • Must start with “10” or “20”

​
CE Validation

  • Must be 9-12 characters
  • Alphanumeric

​
Business Rules

  • Facturas require RUC: Attempting to create a factura with DNI or CE will result in error
  • Automatic tax calculation: IGV (18%) is calculated automatically
  • Thread-safe numbering: Uses database row locking to ensure unique sequential numbers

Build docs developers (and LLMs) love

Get started for freeTalk to us