Creating Debit Notes

Overview

Debit Notes (Notas de Débito) are used to increase the total amount of a previously issued invoice or boleta. Common use cases include interest charges, penalties, or additional services.

Service Layer Only: Debit notes are currently implemented in the DocumentService class but do not yet have REST API endpoints exposed. To use this functionality, you’ll need to interact directly with the service layer in your Laravel application. REST API endpoints are planned for a future release.

Prerequisites

An existing invoice or boleta to modify
Configured company and branch
Valid reason code for the debit note

Reason Codes

SUNAT defines specific codes for debit note reasons:

Code	Description	Use Case
`01`	Interest on arrears	Late payment interest
`02`	Penalty increase	Contract penalties
`03`	Expenses incurred by seller	Additional costs
`10`	Adjustment - Value increase	Price correction upward
`11`	Adjustment - Other concepts	Other valid adjustments

Creating a Debit Note

{
  "company_id": 1,
  "branch_id": 1,
  "serie": "FD01",
  "fecha_emision": "2024-04-20",
  "moneda": "PEN",
  "tipo_doc_afectado": "01",
  "num_doc_afectado": "F001-00000123",
  "cod_motivo": "01",
  "des_motivo": "Interés por mora - Factura vencida el 15/03/2024",
  "client": {
    "tipo_documento": "6",
    "numero_documento": "20123456789",
    "razon_social": "EMPRESA CLIENTE SAC",
    "direccion": "Av. Los Alamos 123",
    "email": "[email protected]"
  },
  "detalles": [
    {
      "codigo": "INT-001",
      "descripcion": "Interés por mora - 30 días de retraso",
      "unidad": "ZZ",
      "cantidad": 1,
      "mto_valor_unitario": 295.00,
      "porcentaje_igv": 18,
      "tip_afe_igv": "10"
    }
  ]
}

Success Response

{
  "success": true,
  "data": {
    "id": 25,
    "company_id": 1,
    "branch_id": 1,
    "tipo_documento": "08",
    "serie": "FD01",
    "correlativo": "00000025",
    "numero_completo": "FD01-00000025",
    "tipo_doc_afectado": "01",
    "num_doc_afectado": "F001-00000123",
    "cod_motivo": "01",
    "des_motivo": "Interés por mora - Factura vencida el 15/03/2024",
    "fecha_emision": "2024-04-20",
    "moneda": "PEN",
    "mto_oper_gravadas": 295.00,
    "mto_igv": 53.10,
    "mto_imp_venta": 348.10,
    "estado_sunat": "PENDIENTE"
  },
  "message": "Nota de débito creada correctamente"
}

Required Fields

company_id

integer

required

Company ID issuing the debit note

branch_id

integer

required

Branch ID (must belong to company)

serie

string

required

Debit note series (max 4 characters)

Invoices: “FD01”, “FD02”, etc.
Boletas: “BD01”, “BD02”, etc.

fecha_emision

date

required

Issue date (YYYY-MM-DD)

tipo_doc_afectado

string

required

Affected document type:

01: Invoice (Factura)
03: Boleta

num_doc_afectado

string

required

Complete number of affected document (e.g., “F001-00000123”)

cod_motivo

string

required

Reason code: 01, 02, 03, 10, or 11

des_motivo

string

required

Reason description (max 250 characters)

moneda

string

required

Currency: PEN or USD (must match original)

Unlike credit notes, debit notes for invoices can only reference document types 01 (Invoice) or 03 (Boleta). They cannot reference other debit/credit notes.

Details Array

detalles[].codigo

string

required

Product/service code for the additional charge

detalles[].descripcion

string

required

Clear description of the charge

detalles[].unidad

string

required

Unit of measure (typically “ZZ” for services)

detalles[].cantidad

number

required

Quantity (typically 1 for charges)

detalles[].mto_valor_unitario

number

required

Unit value of the additional charge

detalles[].tip_afe_igv

string

required

Tax affectation type (usually 10 for taxable)

Sending to SUNAT

Debit notes are sent using the same process as invoices:

curl -X POST https://api.example.com/api/debit-notes/25/send-sunat \
  -H "Authorization: Bearer YOUR_TOKEN"

Success Response

{
  "success": true,
  "data": {
    "id": 25,
    "numero_completo": "FD01-00000025",
    "estado_sunat": "ACEPTADO",
    "xml_path": "storage/companies/1/debit-notes/xml/...",
    "cdr_path": "storage/companies/1/debit-notes/cdr/...",
    "respuesta_sunat": {
      "code": "0",
      "description": "La Nota de Debito ha sido aceptada"
    }
  },
  "message": "Nota de débito enviada correctamente a SUNAT"
}

Downloading Documents

Download XML

curl -X GET https://api.example.com/api/debit-notes/25/download-xml \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o debit-note.xml

Download CDR

curl -X GET https://api.example.com/api/debit-notes/25/download-cdr \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o R-FD01-00000025.zip

Download PDF

curl -X GET https://api.example.com/api/debit-notes/25/download-pdf?format=A4 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o debit-note.pdf

Querying Debit Notes

curl -X GET "https://api.example.com/api/debit-notes?company_id=1&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 SUNAT status
fecha_desde: Start date
fecha_hasta: End date
per_page: Items per page

Advanced Features

Custom Legends

Add custom text to appear on the document:

{
  "leyendas": [
    {
      "code": "2000",
      "value": "Pago debe realizarse dentro de 5 días hábiles"
    }
  ]
}

The API automatically generates the standard amount legend (code 1000) with the total in words.

Additional Data

Include extra information for internal use:

{
  "datos_adicionales": {
    "contrato": "CONT-2024-001",
    "area_responsable": "Créditos y Cobranzas",
    "aprobado_por": "Maria Rodriguez",
    "notas_internas": "Cliente notificado el 10/03/2024"
  }
}

Implementation Details

From app/Services/DocumentService.php:1000-1114, the debit note creation process:

Validates company and branch relationship
Creates or retrieves client (must match original)
Generates automatic correlative number
Processes details and calculates totals
Generates automatic legends
Stores with status PENDIENTE

Automatic Calculations

The API handles:

Line item calculations (quantity × unit value)
IGV calculation per item
Subtotals by tax category
Total IGV
Final amount

Common Errors

Error	Cause	Solution
Referenced document not found	Invalid `num_doc_afectado`	Verify original document exists
Client mismatch	Different client than original	Use exact client from original
Invalid reason code	Wrong `cod_motivo`	Use valid code: 01, 02, 03, 10, 11
Currency mismatch	Different currency than original	Match original document currency
Invalid document type	Wrong `tipo_doc_afectado`	Only 01 (Invoice) or 03 (Boleta)

Best Practices

Provide clear descriptions - Explain the reason for the additional charge
Reference complete document numbers - Include series (e.g., “F001-00000123”)
Match client exactly - Use same client data as original document
Document the business reason - Keep detailed records of why debit note was issued
Verify original is accepted - Original document must be ACEPTADO by SUNAT
Use appropriate reason codes - Choose the code that best matches the situation

Use Case Examples

Late Payment Interest Calculation

{
  "cod_motivo": "01",
  "des_motivo": "Interés moratorio: 30 días x 5% mensual sobre S/ 5,900.00",
  "detalles": [
    {
      "codigo": "INT-MORA",
      "descripcion": "Interés por mora - 30 días de atraso",
      "unidad": "ZZ",
      "cantidad": 1,
      "mto_valor_unitario": 295.00,
      "porcentaje_igv": 18,
      "tip_afe_igv": "10"
    }
  ]
}

Penalty for Contract Breach

{
  "cod_motivo": "02",
  "des_motivo": "Penalidad según cláusula 8.3 del contrato - Retraso en entrega",
  "detalles": [
    {
      "codigo": "PEN-CONT",
      "descripcion": "Penalidad contractual por incumplimiento de plazo",
      "unidad": "ZZ",
      "cantidad": 1,
      "mto_valor_unitario": 500.00,
      "porcentaje_igv": 18,
      "tip_afe_igv": "10"
    }
  ]
}

Additional Shipping Costs

{
  "cod_motivo": "03",
  "des_motivo": "Gastos adicionales de transporte a zona de difícil acceso",
  "detalles": [
    {
      "codigo": "TRANS-ADIC",
      "descripcion": "Flete adicional a zona rural",
      "unidad": "ZZ",
      "cantidad": 1,
      "mto_valor_unitario": 200.00,
      "porcentaje_igv": 18,
      "tip_afe_igv": "10"
    }
  ]
}

Validation Rules

Validations enforced by app/Http/Requests/StoreDebitNoteRequest.php:

Serie: Required, max 4 characters
tipo_doc_afectado: Must be 01 or 03 only
cod_motivo: Must be 01, 02, 03, 10, or 11
Client document type: Must be 0, 1, 4, or 6
Details: At least 1 item required
All amounts: Must be ≥ 0

Differences from Credit Notes

Aspect	Debit Note	Credit Note
Purpose	Increase amount	Decrease amount
Reason codes	01, 02, 03, 10, 11	01-13
Affect types	01, 03 only	01, 03, 07, 08
Common use	Interest, penalties	Returns, corrections
Effect	Adds to debt	Reduces debt

Get Started

Core Concepts

Guides

Advanced

Overview

Prerequisites

Reason Codes

Creating a Debit Note

Success Response

Required Fields

Details Array

Sending to SUNAT

Success Response

Downloading Documents

Download XML

Download CDR

Download PDF

Querying Debit Notes

Query Parameters

Advanced Features

Custom Legends

Additional Data

Implementation Details

Automatic Calculations

Common Errors

Best Practices

Use Case Examples

Late Payment Interest Calculation

Penalty for Contract Breach

Additional Shipping Costs

Validation Rules

Differences from Credit Notes

Next Steps

Credit Notes

PDF Generation

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Advanced

​Overview

​Prerequisites

​Reason Codes

​Creating a Debit Note

​Success Response

​Required Fields

​Details Array

​Sending to SUNAT

​Success Response

​Downloading Documents

​Download XML

​Download CDR

​Download PDF

​Querying Debit Notes

​Query Parameters

​Advanced Features

​Custom Legends

​Additional Data

​Implementation Details

​Automatic Calculations

​Common Errors

​Best Practices

​Use Case Examples

​Late Payment Interest Calculation

​Penalty for Contract Breach

​Additional Shipping Costs

​Validation Rules

​Differences from Credit Notes

​Next Steps

Credit Notes

PDF Generation

Build docs developers (and LLMs) love

Overview

Prerequisites

Reason Codes

Creating a Debit Note

Success Response

Required Fields

Details Array

Sending to SUNAT

Success Response

Downloading Documents

Download XML

Download CDR

Download PDF

Querying Debit Notes

Query Parameters

Advanced Features

Custom Legends

Additional Data

Implementation Details

Automatic Calculations

Common Errors

Best Practices

Use Case Examples

Late Payment Interest Calculation

Penalty for Contract Breach

Additional Shipping Costs

Validation Rules

Differences from Credit Notes

Next Steps