Creating Credit Notes

Overview

Credit Notes (Notas de Crédito) are used to correct or cancel previously issued invoices or boletas. They reduce the total amount owed by the client.

Service Layer Only: Credit 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 correct
Configured company and branch
Valid reason code for the credit note

Reason Codes

SUNAT defines specific codes for credit note reasons:

Code	Description	Use Case
`01`	Cancellation of operation	Full cancellation
`02`	Cancellation due to error in RUC	Wrong client RUC
`03`	Correction due to error in description	Wrong product description
`04`	Global discount	Volume discount
`05`	Discount per item	Item-level discount
`06`	Total return	Full product return
`07`	Partial return	Partial product return
`08`	Bonus	Promotional bonus
`09`	Price decrease	Price adjustment
`10`	Other concept	Other valid reasons
`11`	Transfer adjustments
`12`	Expenses incurred for free sales
`13`	Free bonuses

Creating a Credit Note

Full Cancellation

{
  "company_id": 1,
  "branch_id": 1,
  "serie": "FC01",
  "fecha_emision": "2024-03-15",
  "moneda": "PEN",
  "tipo_doc_afectado": "01",
  "num_doc_afectado": "F001-00000123",
  "cod_motivo": "01",
  "des_motivo": "Anulación de la operación",
  "forma_pago_tipo": "Contado",
  "client": {
    "tipo_documento": "6",
    "numero_documento": "20123456789",
    "razon_social": "EMPRESA CLIENTE SAC",
    "direccion": "Av. Los Alamos 123",
    "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": "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": 50,
    "company_id": 1,
    "branch_id": 1,
    "tipo_documento": "07",
    "serie": "FC01",
    "correlativo": "00000050",
    "numero_completo": "FC01-00000050",
    "tipo_doc_afectado": "01",
    "num_doc_afectado": "F001-00000123",
    "cod_motivo": "01",
    "des_motivo": "Anulación de la operación",
    "fecha_emision": "2024-03-15",
    "moneda": "PEN",
    "mto_oper_gravadas": 5000.00,
    "mto_igv": 900.00,
    "mto_imp_venta": 5900.00,
    "estado_sunat": "PENDIENTE"
  },
  "message": "Nota de crédito creada correctamente"
}

Required Fields

company_id

integer

required

Company ID issuing the credit note

branch_id

integer

required

Branch ID (must belong to company)

serie

string

required

Credit note series (max 4 characters)

Invoices: “FC01”, “FC02”, etc.
Boletas: “BC01”, “BC02”, etc.

fecha_emision

date

required

Issue date (YYYY-MM-DD)

tipo_doc_afectado

string

required

Affected document type:

01: Invoice (Factura)
03: Boleta
07: Credit Note
08: Debit Note

num_doc_afectado

string

required

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

cod_motivo

string

required

Reason code (01-13, see table above)

des_motivo

string

required

Reason description (max 250 characters)

moneda

string

required

Currency: PEN or USD

The credit note must reference an existing, SUNAT-accepted document. The client information must match the original document.

Details Array

The details array should match or be a subset of the original document:

detalles[].codigo

string

required

Product/service code (should match original)

detalles[].descripcion

string

required

Item description

detalles[].unidad

string

required

Unit of measure

detalles[].cantidad

number

required

Quantity to credit (must be ≤ original quantity)

detalles[].mto_valor_unitario

number

required

Unit value (should match original)

detalles[].tip_afe_igv

string

required

Tax affectation (should match original)

Sending to SUNAT

Credit notes are sent the same way as invoices:

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

Success Response

{
  "success": true,
  "data": {
    "id": 50,
    "numero_completo": "FC01-00000050",
    "estado_sunat": "ACEPTADO",
    "xml_path": "storage/companies/1/credit-notes/xml/...",
    "cdr_path": "storage/companies/1/credit-notes/cdr/...",
    "respuesta_sunat": {
      "code": "0",
      "description": "La Nota de Credito ha sido aceptada"
    }
  },
  "message": "Nota de crédito enviada correctamente a SUNAT"
}

Advanced Features

Credit with Payment Terms

If the original was on credit, you can specify payment terms:

{
  "forma_pago_tipo": "Credito",
  "forma_pago_cuotas": [
    {
      "monto": 2950.00,
      "fecha_pago": "2024-04-15"
    },
    {
      "monto": 2950.00,
      "fecha_pago": "2024-05-15"
    }
  ]
}

Link the credit note to related guides or other documents:

{
  "guias": [
    {
      "tipo_doc": "09",
      "nro_doc": "T001-00000789"
    }
  ]
}

Custom Legends

{
  "leyendas": [
    {
      "code": "1000",
      "value": "CINCO MIL NOVECIENTOS CON 00/100 SOLES"
    },
    {
      "code": "2000",
      "value": "Nota informativa adicional"
    }
  ]
}

The API automatically generates the standard amount legend (code 1000) if not provided.

Downloading Documents

Download XML

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

Download CDR

curl -X GET https://api.example.com/api/credit-notes/50/download-cdr \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o R-FC01-00000050.zip

Download PDF

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

Querying Credit Notes

curl -X GET "https://api.example.com/api/credit-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 status
fecha_desde: Start date
fecha_hasta: End date
per_page: Items per page

Implementation Details

From app/Services/DocumentService.php:880-998, the credit note creation:

Validates company/branch relationship
Creates or retrieves client
Generates automatic correlative for series
Processes details and calculates totals
Validates tax affectation types
Generates automatic legends
Stores with status PENDIENTE

Automatic Calculations

The API automatically calculates:

Line item totals (quantity × unit value)
IGV per item
Subtotals by tax type (gravadas, exoneradas, inafectas)
Total IGV
Total amount

Common Errors

Error	Cause	Solution
Referenced document not found	`num_doc_afectado` doesn’t exist	Verify document number exists
Client mismatch	Different client than original	Use same client as original document
Invalid reason code	Wrong `cod_motivo`	Use valid code from 01-13
Amount exceeds original	Credit exceeds original amount	Verify quantities and unit values
Document not accepted	Original not accepted by SUNAT	Original must be ACEPTADO first

Best Practices

Always reference the complete document number including series (e.g., “F001-00000123”)
Use descriptive reason descriptions for audit trails
Match client data exactly from the original document
Verify original document is accepted before creating credit note
Keep item codes consistent with original document for tracking
Document business reason in des_motivo field clearly

Special Cases

Correcting RUC Error

For code 02 (error in RUC):

{
  "cod_motivo": "02",
  "des_motivo": "Corrección por error en RUC - Se emitirá nuevo comprobante",
  "client": {
    "tipo_documento": "6",
    "numero_documento": "20123456789",
    "razon_social": "CLIENTE CORRECTO SAC"
  }
}

After sending this credit note, issue a new invoice with the correct client information.

Global Discount

For code 04 (global discount):

{
  "cod_motivo": "04",
  "des_motivo": "Descuento global por pronto pago",
  "detalles": [
    {
      "codigo": "DESC-GLOBAL",
      "descripcion": "Descuento por pronto pago 10%",
      "unidad": "ZZ",
      "cantidad": 1,
      "mto_valor_unitario": 590.00,
      "porcentaje_igv": 18,
      "tip_afe_igv": "10"
    }
  ]
}

Validation Rules

These validations are enforced by app/Http/Requests/StoreCreditNoteRequest.php:

Serie is required and max 4 characters
tipo_doc_afectado must be: 01, 03, 07, or 08
cod_motivo must be: 01-13
Client document type must be: 0, 1, 4, or 6
Details array must have at least 1 item
All monetary values must be ≥ 0

Get Started

Core Concepts

Guides

Advanced

Overview

Prerequisites

Reason Codes

Creating a Credit Note

Full Cancellation

Success Response

Required Fields

Details Array

Sending to SUNAT

Success Response

Advanced Features

Credit with Payment Terms

Custom Legends

Downloading Documents

Download XML

Download CDR

Download PDF

Querying Credit Notes

Query Parameters

Implementation Details

Automatic Calculations

Common Errors

Best Practices

Special Cases

Correcting RUC Error

Global Discount

Validation Rules

Next Steps

Debit Notes

PDF Generation

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Advanced

​Overview

​Prerequisites

​Reason Codes

​Creating a Credit Note

​Full Cancellation

​Success Response

​Required Fields

​Details Array

​Sending to SUNAT

​Success Response

​Advanced Features

​Credit with Payment Terms

​Related Documents

​Custom Legends

​Downloading Documents

​Download XML

​Download CDR

​Download PDF

​Querying Credit Notes

​Query Parameters

​Implementation Details

​Automatic Calculations

​Common Errors

​Best Practices

​Special Cases

​Correcting RUC Error

​Global Discount

​Validation Rules

​Next Steps

Debit Notes

PDF Generation

Build docs developers (and LLMs) love

Overview

Prerequisites

Reason Codes

Creating a Credit Note

Full Cancellation

Success Response

Required Fields

Details Array

Sending to SUNAT

Success Response

Advanced Features

Credit with Payment Terms

Related Documents

Custom Legends

Downloading Documents

Download XML

Download CDR

Download PDF

Querying Credit Notes

Query Parameters

Implementation Details

Automatic Calculations

Common Errors

Best Practices

Special Cases

Correcting RUC Error

Global Discount

Validation Rules

Next Steps