Nota de Crédito - Santo Domingo Facturación Electrónica

Descripción

Las Notas de Crédito (tipo documento 07) se utilizan para anular o reducir el valor de facturas o boletas previamente emitidas. El sistema genera automáticamente la serie según el documento afectado:

FC01: Para notas de crédito que afectan Facturas (01)
BC01: Para notas de crédito que afectan Boletas (03)

Flujo de Trabajo

Crear nota de crédito: POST /api/notas-credito - Genera el registro y XML firmado
Enviar a SUNAT: POST /api/notas-credito/{id}/enviar - Envío sincrónico vía SOAP
Obtener CDR: GET /api/notas-credito/{id}/cdr - Descarga la constancia de recepción

Cuando una nota de crédito es aceptada por SUNAT, la venta original se marca automáticamente como anulada (estado = 2).

POST /api/notas-credito

Crea una nueva nota de crédito asociada a una venta existente.

Request Body

id_venta

integer

required

ID de la venta a afectar (factura o boleta existente)

motivo_id

integer

required

ID del motivo de la nota de crédito. Obtener lista desde GET /api/notas-credito/motivos

descripcion_motivo

string

Descripción personalizada del motivo (opcional, usa la descripción del motivo por defecto si se omite)

Motivos de Nota de Crédito (Catálogo SUNAT 09)

Código	Descripción
01	Anulación de la operación
02	Anulación por error en el RUC
03	Corrección por error en la descripción
04	Descuento global
05	Descuento por ítem
06	Devolución total
07	Devolución por ítem
08	Bonificación
09	Disminución en el valor
10	Otros conceptos

Lógica del Servidor

Valida que la venta exista y pertenezca a la empresa del usuario
Determina la serie automáticamente:
- Si tipo_doc_afectado = '01' (Factura) → Serie FC01
- Si tipo_doc_afectado = '03' (Boleta) → Serie BC01
Genera el número correlativo (máximo + 1) sincronizado con documentos_empresas
Copia los montos de la venta original (subtotal, IGV, total)
Genera el XML UBL 2.1 firmado digitalmente usando Greenter
Calcula el hash CPE del XML
Almacena el XML en storage/app/sunat/xml/{ruc}/

Response

success

boolean

Indica si la operación fue exitosa

data

object

Objeto de la nota de crédito creada

Show Estructura de data

integer

ID interno de la nota de crédito

serie

string

Serie generada automáticamente (FC01 o BC01)

numero

integer

Número correlativo

tipo_doc_afectado

string

Código del documento afectado (01=Factura, 03=Boleta)

serie_num_afectado

string

Serie y número del documento afectado (ej: “F001-123”)

monto_total

decimal

Monto total de la nota (copiado de la venta)

moneda

string

Código de moneda (PEN, USD)

estado

string

Estado actual: pendiente, aceptado, rechazado

nombre_xml

string

Nombre del archivo XML generado (formato: -07--)

hash_cpe

string

Hash SHA256 del XML firmado

xml_url

string

Ruta relativa al archivo XML en storage

venta

object

Datos de la venta afectada (incluye cliente y productos)

motivo

object

Datos del motivo seleccionado (código SUNAT y descripción)

xml

object

Información sobre el XML generado

Show Estructura de xml

success

boolean

true si el XML se generó correctamente

nombre_archivo

string

Nombre del archivo XML (sin extensión)

hash

string

Hash del XML firmado

Ejemplo de Request

{
  "id_venta": 145,
  "motivo_id": 1,
  "descripcion_motivo": "Anulación por solicitud del cliente"
}

Ejemplo de Response (201 Created)

{
  "success": true,
  "data": {
    "id": 23,
    "id_venta": 145,
    "motivo_id": 1,
    "serie": "FC01",
    "numero": 34,
    "tipo_doc_afectado": "01",
    "serie_num_afectado": "F001-145",
    "descripcion_motivo": "Anulación por solicitud del cliente",
    "monto_subtotal": "84.75",
    "monto_igv": "15.25",
    "monto_total": "100.00",
    "moneda": "PEN",
    "fecha_emision": "2026-03-06",
    "estado": "pendiente",
    "hash_cpe": "tK8fZmQ7fZQ...",
    "xml_url": "sunat/xml/20612706702/20612706702-07-FC01-00000034.xml",
    "nombre_xml": "20612706702-07-FC01-00000034",
    "id_empresa": 1,
    "id_usuario": 5,
    "venta": {
      "id_venta": 145,
      "serie": "F001",
      "numero": 145,
      "total": "100.00",
      "cliente": {
        "documento": "20123456789",
        "datos": "EMPRESA EJEMPLO SAC"
      }
    },
    "motivo": {
      "id": 1,
      "tipo": "NC",
      "codigo_sunat": "01",
      "descripcion": "Anulación de la operación"
    }
  },
  "xml": {
    "success": true,
    "nombre_archivo": "20612706702-07-FC01-00000034",
    "hash": "tK8fZmQ7fZQ..."
  }
}

POST /api/notas-credito//enviar

Envía la nota de crédito generada a SUNAT para su aceptación.

Path Parameters

integer

required

ID de la nota de crédito a enviar

Flujo SUNAT (Sincrónico)

Lee el XML firmado desde storage/app/sunat/xml/{ruc}/
Se autentica con SUNAT usando credenciales SOL (RUC + usuario + clave)
Envía el XML vía SOAP a la API de SUNAT
Recibe el CDR (Constancia de Recepción) inmediatamente
Almacena el CDR en storage/app/sunat/cdr/{ruc}/R-{nombre}.zip
Actualiza el estado de la nota según la respuesta
Si es aceptada, marca la venta original como anulada

Validaciones

La nota de crédito debe tener XML generado (nombre_xml no nulo)
El archivo XML debe existir en el servidor

Response (Éxito)

success

boolean

true si SUNAT aceptó la nota de crédito

codigo

string

Código de respuesta de SUNAT (ej: “0” = aceptado, “0100” = aceptado con observaciones)

mensaje

string

Descripción de la respuesta de SUNAT

cdr_url

string

Ruta al archivo CDR (ZIP) descargado desde SUNAT

Response (Error)

success

boolean

false si SUNAT rechazó la nota

codigo

string

Código de error de SUNAT

message

string

Descripción del error

Ejemplo de Response (Éxito)

{
  "success": true,
  "codigo": "0",
  "mensaje": "La Nota de Crédito numero FC01-00000034, ha sido aceptada",
  "cdr_url": "sunat/cdr/20612706702/R-20612706702-07-FC01-00000034.zip"
}

Ejemplo de Response (Error)

{
  "success": false,
  "codigo": "2324",
  "message": "El documento afectado por la nota no existe o no está aceptado"
}

GET /api/notas-credito

Obtiene lista paginada de notas de crédito de la empresa.

Query Parameters

page

integer

default:"1"

Número de página

Response

Objeto de paginación Laravel con 15 items por página.

GET /api/notas-credito/

Obtiene detalle completo de una nota de crédito específica.

Path Parameters

integer

required

ID de la nota de crédito

GET /api/notas-credito//cdr

Descarga el archivo CDR (Constancia de Recepción) en formato ZIP.

Path Parameters

integer

required

ID de la nota de crédito

Response

Archivo ZIP para descarga directa.

GET /api/notas-credito/xml/

Descarga el archivo XML de la nota de crédito.

Path Parameters

nombre

string

required

Nombre del archivo XML (con o sin extensión .xml)

Response

Archivo XML para visualización en navegador.

GET /api/notas-credito/buscar-venta

Busca una venta por serie y número para crear una nota de crédito.

Query Parameters

serie

string

required

Serie de la venta (ej: “F001”)

numero

string

required

Número correlativo de la venta

Response

Objeto de venta con cliente y productos relacionados.

GET /api/notas-credito/motivos

Obtiene la lista de motivos disponibles para notas de crédito.

Response

{
  "success": true,
  "data": [
    {
      "id": 1,
      "tipo": "NC",
      "codigo_sunat": "01",
      "descripcion": "Anulación de la operación",
      "estado": true
    },
    {
      "id": 2,
      "tipo": "NC",
      "codigo_sunat": "02",
      "descripcion": "Anulación por error en el RUC",
      "estado": true
    }
  ]
}

Notas Técnicas

Integración con Greenter

El sistema utiliza la librería Greenter para:

Construir objetos UBL 2.1 conformes a SUNAT
Firmar digitalmente el XML con certificado PEM
Enviar vía SOAP al webservice de SUNAT
Procesar la respuesta CDR

Ver SunatService::generarNotaCreditoXml() (línea 319) y enviarNotaCredito() (línea 381).

Certificados Digitales

Se buscan en este orden:

storage/app/sunat/certificados/{ruc}-cert.pem (específico de empresa)
Certificado de prueba configurado en config/sunat.php

Ambientes SUNAT

Si empresa.modo !== 'production':

Usa RUC de prueba: 20000000001
Usuario SOL: MODDATOS
Clave SOL: moddatos
Endpoint beta de SUNAT

Estado de la Venta Original

Cuando una nota de crédito es aceptada por SUNAT (código “0”), la venta afectada se actualiza automáticamente:

$nota->venta->update([
    'estado' => '2',           // Anulada
    'estado_sunat' => '2',     // Anulada en SUNAT
]);

Numeración Automática

El sistema sincroniza la numeración con la tabla documentos_empresas:

$ultimoNumero = max(
    NotaCredito::where('serie', $serie)->max('numero'),
    DB::table('documentos_empresas')->where('serie', $serie)->value('numero')
);

Esto permite configurar un número base desde la UI de administración.

Errores Comunes

Código	Descripción	Solución
2324	Documento afectado no existe	Verificar que la factura/boleta esté aceptada por SUNAT
2800	Serie no autorizada	Verificar configuración de series en SUNAT
1033	Certificado inválido	Renovar certificado digital PEM
422	XML no generado	Llamar primero a `POST /api/notas-credito`

Autenticación

Ventas y Facturación

Notas de Crédito/Débito

Guías de Remisión

Cotizaciones

Compras

Productos e Inventario

Clientes y Proveedores

Finanzas

Dashboard

​Descripción

​Flujo de Trabajo

​POST /api/notas-credito

​Request Body

​Motivos de Nota de Crédito (Catálogo SUNAT 09)

​Lógica del Servidor

​Response

​Ejemplo de Request

​Ejemplo de Response (201 Created)

​POST /api/notas-credito//enviar

​Path Parameters

​Flujo SUNAT (Sincrónico)

​Validaciones

​Response (Éxito)

​Response (Error)

​Ejemplo de Response (Éxito)

​Ejemplo de Response (Error)

​GET /api/notas-credito

​Query Parameters

​Response

​GET /api/notas-credito/

​Path Parameters

​GET /api/notas-credito//cdr

​Path Parameters

​Response

​GET /api/notas-credito/xml/

​Path Parameters

​Response

​GET /api/notas-credito/buscar-venta

​Query Parameters

​Response

​GET /api/notas-credito/motivos

​Response

​Notas Técnicas

​Integración con Greenter

​Certificados Digitales

​Ambientes SUNAT

​Estado de la Venta Original

​Numeración Automática

​Errores Comunes

Build docs developers (and LLMs) love

Descripción

Flujo de Trabajo

POST /api/notas-credito

Request Body

Motivos de Nota de Crédito (Catálogo SUNAT 09)

Lógica del Servidor

Response

Ejemplo de Request

Ejemplo de Response (201 Created)

POST /api/notas-credito//enviar

Path Parameters

Flujo SUNAT (Sincrónico)

Validaciones

Response (Éxito)

Response (Error)

Ejemplo de Response (Éxito)

Ejemplo de Response (Error)

GET /api/notas-credito

Query Parameters

Response

GET /api/notas-credito/

Path Parameters

GET /api/notas-credito//cdr

Path Parameters

Response

GET /api/notas-credito/xml/

Path Parameters

Response

GET /api/notas-credito/buscar-venta

Query Parameters

Response

GET /api/notas-credito/motivos

Response

Notas Técnicas

Integración con Greenter

Certificados Digitales

Ambientes SUNAT

Estado de la Venta Original

Numeración Automática

Errores Comunes