Creating Invoices (Facturas)

Overview

Facturas (Invoices) are the primary electronic documents for B2B transactions in Peru. This guide covers creating, sending to SUNAT, and managing invoices using the API.

Prerequisites

Before creating invoices, ensure you have:

A configured company with valid SUNAT credentials
At least one active branch with configured invoice series
Valid client information (RUC for invoices)

Creating an Invoice

Basic Invoice Creation

Prepare the Request

Create a POST request to /api/invoices with the invoice data.

Send to SUNAT

After creation, send the invoice to SUNAT using /api/invoices/{id}/send-sunat.

Download Documents

Download XML, CDR, and PDF using the respective endpoints.

Complete Request Example

{
  "company_id": 1,
  "branch_id": 1,
  "serie": "F001",
  "fecha_emision": "2024-03-15",
  "fecha_vencimiento": "2024-04-15",
  "moneda": "PEN",
  "tipo_operacion": "0101",
  "forma_pago_tipo": "Credito",
  "forma_pago_cuotas": [
    {
      "moneda": "PEN",
      "monto": 590.00,
      "fecha_pago": "2024-04-15"
    }
  ],
  "client": {
    "tipo_documento": "6",
    "numero_documento": "20123456789",
    "razon_social": "EMPRESA CLIENTE SAC",
    "nombre_comercial": "Cliente Comercial",
    "direccion": "Av. Los Alamos 123",
    "ubigeo": "150101",
    "distrito": "Lima",
    "provincia": "Lima",
    "departamento": "Lima",
    "telefono": "01-1234567",
    "email": "[email protected]"
  },
  "detalles": [
    {
      "codigo": "PROD001",
      "descripcion": "Laptop HP ProBook 450 G8",
      "unidad": "NIU",
      "cantidad": 2,
      "mto_valor_unitario": 2500.00,
      "porcentaje_igv": 18,
      "tip_afe_igv": "10",
      "codigo_producto_sunat": "43211500"
    },
    {
      "codigo": "SERV001",
      "descripcion": "Instalación y configuración",
      "unidad": "ZZ",
      "cantidad": 1,
      "mto_valor_unitario": 500.00,
      "porcentaje_igv": 18,
      "tip_afe_igv": "10"
    }
  ]
}

Success Response

{
  "success": true,
  "data": {
    "id": 123,
    "company_id": 1,
    "branch_id": 1,
    "client_id": 45,
    "tipo_documento": "01",
    "serie": "F001",
    "correlativo": "00000123",
    "numero_completo": "F001-00000123",
    "fecha_emision": "2024-03-15",
    "moneda": "PEN",
    "mto_oper_gravadas": 5000.00,
    "mto_igv": 900.00,
    "mto_imp_venta": 5900.00,
    "estado_sunat": "PENDIENTE",
    "company": { ... },
    "branch": { ... },
    "client": { ... }
  },
  "message": "Factura creada correctamente"
}

Required Fields

company_id

integer

required

ID of the company issuing the invoice

branch_id

integer

required

ID of the branch (must belong to the company)

serie

string

required

Invoice series (max 4 characters, e.g., “F001”)

fecha_emision

date

required

Issue date in YYYY-MM-DD format

moneda

string

required

Currency code: PEN (Soles) or USD (Dollars)

tipo_operacion

string

default:"0101"

Operation type:

0101: Internal sale
0200: Export
0401: Non-domiciled sale

forma_pago_tipo

string

required

Payment type: Contado (Cash) or Credito (Credit)

Client Object

client.tipo_documento

string

required

Document type:

6: RUC (required for invoices)
4: Carnet de Extranjería
1: DNI (only for amounts < 700 PEN)

client.numero_documento

string

required

Client’s document number (11 digits for RUC)

Client’s legal name

Details Array

detalles[].codigo

string

required

Product/service code

detalles[].descripcion

string

required

Item description (max 500 characters)

detalles[].unidad

string

required

Unit of measure (SUNAT catalog 03):

NIU: Units
ZZ: Service
KGM: Kilograms

detalles[].cantidad

number

required

Quantity (minimum 0.001)

detalles[].mto_valor_unitario

number

required

Unit value (without taxes)

detalles[].tip_afe_igv

string

required

Tax affectation type:

10: Taxable - IGV
20: Exempt
30: Unaffected
40: Export

detalles[].porcentaje_igv

number

default:"18"

IGV percentage (usually 18%)

Sending to SUNAT

After creating an invoice, send it to SUNAT for validation:

curl -X POST https://api.example.com/api/invoices/123/send-sunat \
  -H "Authorization: Bearer YOUR_TOKEN"

Success Response

{
  "success": true,
  "data": {
    "id": 123,
    "numero_completo": "F001-00000123",
    "estado_sunat": "ACEPTADO",
    "xml_path": "storage/companies/1/invoices/xml/...",
    "cdr_path": "storage/companies/1/invoices/cdr/...",
    "respuesta_sunat": {
      "id": "F001-00000123",
      "code": "0",
      "description": "La Factura numero F001-00000123, ha sido aceptada"
    }
  },
  "message": "Factura enviada correctamente a SUNAT"
}

Error Response

{
  "success": false,
  "data": {
    "id": 123,
    "estado_sunat": "RECHAZADO"
  },
  "message": "Error al enviar a SUNAT: El RUC del cliente no existe",
  "error_code": "2324"
}

The API automatically generates the correlative number for each series. The invoice totals (IGV, subtotals) are calculated automatically from the details.

Downloading Documents

Download XML

curl -X GET https://api.example.com/api/invoices/123/download-xml \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o invoice.xml

Download CDR (SUNAT Response)

curl -X GET https://api.example.com/api/invoices/123/download-cdr \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o R-F001-00000123.zip

Download PDF

curl -X GET https://api.example.com/api/invoices/123/download-pdf?format=A4 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o invoice.pdf

Available PDF formats: A4, A5, 80mm, ticket

Advanced Features

Credit Payment with Installments

{
  "forma_pago_tipo": "Credito",
  "forma_pago_cuotas": [
    {
      "moneda": "PEN",
      "monto": 2000.00,
      "fecha_pago": "2024-04-15"
    },
    {
      "moneda": "PEN",
      "monto": 2000.00,
      "fecha_pago": "2024-05-15"
    },
    {
      "moneda": "PEN",
      "monto": 1900.00,
      "fecha_pago": "2024-06-15"
    }
  ]
}

Invoice with Perception

{
  "percepcion": {
    "cod_regimen": "01",
    "tasa": 2.00,
    "monto": 118.00,
    "monto_base": 5900.00,
    "monto_total": 6018.00
  }
}

{
  "guias": [
    {
      "tipo_doc": "09",
      "nro_doc": "T001-00000456"
    }
  ],
  "documentos_relacionados": [
    {
      "tipo_doc": "01",
      "nro_doc": "F001-00000100"
    }
  ]
}

Querying Invoices

List invoices with filters:

curl -X GET "https://api.example.com/api/invoices?company_id=1&estado_sunat=ACEPTADO&fecha_desde=2024-03-01&fecha_hasta=2024-03-31" \
  -H "Authorization: Bearer YOUR_TOKEN"

Query Parameters

company_id: Filter by company
branch_id: Filter by branch
estado_sunat: Filter by status (PENDIENTE, ACEPTADO, RECHAZADO)
fecha_desde: Start date (YYYY-MM-DD)
fecha_hasta: End date (YYYY-MM-DD)
per_page: Items per page (default: 15)

Tax Affectation Types

The tip_afe_igv field is critical for correct tax calculation.

Code	Description	IGV
`10`	Taxable - IGV	Yes (18%)
`20`	Exempt	No
`30`	Unaffected	No
`40`	Export	No
`11`	Taxable - Free transfer	No (but calculated for reference)
`17`	Taxable - IVAP (rice)	Yes (4%)

Implementation Notes

The invoice creation process from app/Http/Controllers/Api/InvoiceController.php:71-92 and app/Services/DocumentService.php:34-114:

Validates company and branch relationship
Creates or retrieves client record
Generates automatic correlative number
Processes details based on operation type (export vs. domestic)
Calculates all totals automatically
Generates standard legends
Stores invoice in database with status PENDIENTE

For export operations (tipo_operacion: "0200"), the system automatically sets tip_afe_igv: "40" and calculates with 0% IGV.

Common Errors

Error	Cause	Solution
Branch doesn’t belong to company	`branch_id` doesn’t match `company_id`	Verify branch belongs to the company
Invalid RUC	Client RUC doesn’t exist in SUNAT	Verify RUC with SUNAT first
Invalid series	Series not configured for branch	Configure series in branch settings
Document already accepted	Trying to resend accepted invoice	Only pending invoices can be sent

Best Practices

Always validate client data before creating invoices
Use consistent series for each document type and branch
Store correlative numbers safely to avoid duplicates
Handle SUNAT errors gracefully with proper error codes
Generate PDF after SUNAT acceptance for better QR code data
Keep XML and CDR files for auditing purposes

Get Started

Core Concepts

Guides

Advanced

Overview

Prerequisites

Creating an Invoice

Basic Invoice Creation

Complete Request Example

Success Response

Required Fields

Client Object

Details Array

Sending to SUNAT

Success Response

Error Response

Downloading Documents

Download XML

Download CDR (SUNAT Response)

Download PDF

Advanced Features

Credit Payment with Installments

Invoice with Perception

Querying Invoices

Query Parameters

Tax Affectation Types

Implementation Notes

Common Errors

Best Practices

Next Steps

Credit Notes

PDF Generation

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Advanced

​Overview

​Prerequisites

​Creating an Invoice

​Basic Invoice Creation

​Complete Request Example

​Success Response

​Required Fields

​Client Object

​Details Array

​Sending to SUNAT

​Success Response

​Error Response

​Downloading Documents

​Download XML

​Download CDR (SUNAT Response)

​Download PDF

​Advanced Features

​Credit Payment with Installments

​Invoice with Perception

​Related Documents

​Querying Invoices

​Query Parameters

​Tax Affectation Types

​Implementation Notes

​Common Errors

​Best Practices

​Next Steps

Credit Notes

PDF Generation

Build docs developers (and LLMs) love

Overview

Prerequisites

Creating an Invoice

Basic Invoice Creation

Complete Request Example

Success Response

Required Fields

Client Object

Details Array

Sending to SUNAT

Success Response

Error Response

Downloading Documents

Download XML

Download CDR (SUNAT Response)

Download PDF

Advanced Features

Credit Payment with Installments

Invoice with Perception

Related Documents

Querying Invoices

Query Parameters

Tax Affectation Types

Implementation Notes

Common Errors

Best Practices

Next Steps