Notas de Débito

Pruebas
Producción

Dominio: https://test-api-factura.edw-dev.com

Las notas de débito son documentos electrónicos que se utilizan para aumentar el valor de una factura previamente emitida, aplicar cargos adicionales, intereses por mora, gastos de cobranza, o corregir errores que resulten en un incremento del monto a pagar.

Información General

Código SRI: 05
Tipo de documento: Nota de Débito
Uso: Cargos adicionales, intereses, gastos, correcciones al alza
Cliente requerido: Sí
Documento de soporte: Requerido (factura original)
Emisión automática: Opcional

Endpoint

POST /api/v1/documents/create

Headers Requeridos

Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}

Parámetros Específicos

Parámetro	Tipo	Requerido	Descripción
`sri_code_document`	string	Sí	Debe ser `"05"` para notas de débito
`send_to_emit`	boolean	No	Si se debe emitir automáticamente al SRI
`customer`	object	Sí	Información del cliente (mismo de la factura)
`document`	object	Sí	Información del documento y soporte
`items`	array	Sí	Array de cargos adicionales
`aditional_fields`	array	No	Campos adicionales

Estructura del Documento (con soporte)

{
  "date": "2024-01-15",
  "establishment": "001",
  "point_of_emission": "001",
  "support_code_document": "01",
  "support_date": "2024-01-10",
  "support_reason": "Intereses por mora",
  "support_document_number": "001-001-000000012"
}

Campos de Soporte Requeridos

Campo	Descripción	Ejemplo
`support_code_document`	Código del documento original	`"01"` (Factura)
`support_date`	Fecha del documento original	`"2024-01-10"`
`support_reason`	Motivo de la nota de débito	`"Intereses por mora"`
`support_document_number`	Número del documento original	`"001-001-000000012"`

Ejemplos de Implementación

Nota de Débito Simple (Intereses por Mora)

Solicitud

{
  "sri_code_document": "05",
  "send_to_emit": true,
  "customer": {
    "identification_number": "0123456789",
    "name": "Juan",
    "lastname": "Pérez",
    "identification_type": "CEDULA",
    "email": "[email protected]",
    "address": "Quito, Ecuador"
  },
  "document": {
    "date": "2024-01-15",
    "establishment": "001",
    "point_of_emission": "001",
    "support_code_document": "01",
    "support_date": "2024-01-10",
    "support_reason": "Intereses por mora en el pago",
    "support_document_number": "001-001-000000012"
  },
  "items": [
    {
      "code": "INT-001",
      "description": "Intereses por mora - 30 días",
      "rate": 25.00,
      "quantity": 1,
      "subtotal": 25.00,
      "taxes": [
        {
          "code": "2",
          "percentaje_code": "2",
          "percentaje_tax": 12,
          "total_tax": 3.00
        }
      ]
    }
  ]
}

Respuesta Exitosa (201)

{
  "message": "Documento creado exitosamente",
  "status": "CREATED",
  "payload": {
    "id": 123456790,
    "environment": "PROD",
    "number": 1,
    "date": "2024-01-15",
    "subtotal": "25.00",
    "tax_amount": "3.00",
    "total": "28.00",
    "type": "debit_note",
    "customer": {
      "id": 987654321,
      "full_name": "Juan Pérez",
      "email": "[email protected]",
      "identification_type": "cedula",
      "identification_number": "0123456789"
    },
    "sri": {
      "access_key": "1501202405012345678900110010010000000011234567890",
      "status": "AUTORIZADO",
      "sequential_number": "000000001",
      "establishment": "001",
      "point_emission": "001",
      "document_number": "001-001-000000001",
      "type_document": "NOTA DEBITO",
      "code_document": "05"
    },
    "support": {
      "code_document": "01",
      "document_number": "001-001-000000012",
      "date": "2024-01-10",
      "reason": "Intereses por mora en el pago"
    },
    "items": [
      {
        "position": 1,
        "code": "INT-001",
        "description": "Intereses por mora - 30 días",
        "rate": "25.00",
        "quantity": "1.00",
        "subtotal": "25.00",
        "total_tax": "3.00",
        "total": "28.00"
      }
    ]
  }
}

Nota de Débito con Múltiples Cargos

Solicitud

{
  "sri_code_document": "05",
  "customer": {
    "identification_number": "1234567890",
    "name": "Empresa",
    "lastname": "Comercial S.A.",
    "identification_type": "RUC",
    "email": "[email protected]",
    "address": "Guayaquil, Ecuador"
  },
  "document": {
    "date": "2024-10-09",
    "sri_establishment": "001",
    "sri_point_emi": "004",
    "support_code_document": "01",
    "support_date": "2024-09-15",
    "support_reason": "Cargos adicionales por servicios",
    "support_document_number": "001-001-000000025"
  },
  "items": [
    {
      "code": "CARGO-001",
      "description": "Gastos de cobranza",
      "rate": 50.00,
      "quantity": 1,
      "subtotal": 50.00,
      "taxes": [
        {
          "code": "2",
          "percentaje_code": "2",
          "percentaje_tax": 12,
          "total_tax": 6.00
        }
      ]
    },
    {
      "code": "CARGO-002",
      "description": "Intereses por mora",
      "rate": 75.00,
      "quantity": 1,
      "subtotal": 75.00,
      "taxes": [
        {
          "code": "2",
          "percentaje_code": "2",
          "percentaje_tax": 12,
          "total_tax": 9.00
        }
      ]
    }
  ],
  "aditional_fields": [
    {
      "key": "Telefono",
      "value": "042345678",
      "type": "sri"
    },
    {
      "key": "Email",
      "value": "[email protected]",
      "type": "sri"
    }
  ]
}

Respuesta con Múltiples Cargos (201)

{
  "message": "Documento creado",
  "status": "CREATED",
  "payload": {
    "id": 1339329971,
    "environment": "TEST",
    "number": 2,
    "date": "2024-10-09",
    "subtotal": "125.00",
    "tax_amount": "15.00",
    "total": "140.00",
    "status": "draft",
    "type": "debit_note",
    "customer": {
      "id": 61247345,
      "full_name": "Empresa Comercial S.A.",
      "email": "[email protected]",
      "identification_type": "ruc",
      "identification_number": "1234567890"
    },
    "sri": {
      "establishment": "001",
      "point_emi": "004",
      "type_document": "NOTA DEBITO",
      "title_document": "Nota de débito",
      "code_document": "05"
    },
    "support": {
      "code_document": "01",
      "document_number": "001-001-000000025",
      "date": "2024-09-15",
      "reason": "Cargos adicionales por servicios"
    },
    "items": [
      {
        "position": 1,
        "code": "CARGO-001",
        "description": "Gastos de cobranza",
        "rate": "50.00",
        "quantity": "1.00",
        "subtotal": "50.00",
        "total_tax": "6.00",
        "total": "56.00"
      },
      {
        "position": 2,
        "code": "CARGO-002",
        "description": "Intereses por mora",
        "rate": "75.00",
        "quantity": "1.00",
        "subtotal": "75.00",
        "total_tax": "9.00",
        "total": "84.00"
      }
    ],
    "taxes": [
      {
        "tax_type": "IVA",
        "tax_name": "12%",
        "tax_rate": "15.00",
        "tax_subtotal": "125.00",
        "tax_code": "2",
        "tax_code_sri": "2"
      }
    ]
  }
}

Ejemplos de Código

curl -X POST "https://dev-facturacion.e-dinky.test/api/v1/documents/create" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "sri_code_document": "05",
    "send_to_emit": true,
    "customer": {
      "identification_number": "0123456789",
      "name": "Juan",
      "lastname": "Pérez",
      "identification_type": "CEDULA",
      "email": "[email protected]",
      "address": "Quito, Ecuador"
    },
    "document": {
      "date": "2024-01-15",
      "establishment": "001",
      "point_of_emission": "001",
      "support_code_document": "01",
      "support_date": "2024-01-10",
      "support_reason": "Intereses por mora en el pago",
      "support_document_number": "001-001-000000012"
    },
    "items": [
      {
        "code": "INT-001",
        "description": "Intereses por mora - 30 días",
        "rate": 25.00,
        "quantity": 1,
        "subtotal": 25.00,
        "taxes": [
          {
            "code": "2",
            "percentaje_code": "2",
            "percentaje_tax": 12,
            "total_tax": 3.00
          }
        ]
      }
    ]
  }'

<?php

use Illuminate\Support\Facades\Http;

$token = 'your-api-token';

$response = Http::withHeaders([
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer ' . $token,
])->post('https://dev-facturacion.e-dinky.test/api/v1/documents/create', [
    'sri_code_document' => '05',
    'send_to_emit' => true,
    'customer' => [
        'identification_number' => '0123456789',
        'name' => 'Juan',
        'lastname' => 'Pérez',
        'identification_type' => 'CEDULA',
        'email' => '[email protected]',
        'address' => 'Quito, Ecuador'
    ],
    'document' => [
        'date' => '2024-01-15',
        'establishment' => '001',
        'point_of_emission' => '001',
        'support_code_document' => '01',
        'support_date' => '2024-01-10',
        'support_reason' => 'Intereses por mora en el pago',
        'support_document_number' => '001-001-000000012'
    ],
    'items' => [
        [
            'code' => 'INT-001',
            'description' => 'Intereses por mora - 30 días',
            'rate' => 25.00,
            'quantity' => 1,
            'subtotal' => 25.00,
            'taxes' => [
                [
                    'code' => '2',
                    'percentaje_code' => '2',
                    'percentaje_tax' => 12,
                    'total_tax' => 3.00
                ]
            ]
        ]
    ]
]);

if ($response->successful()) {
    $document = $response->json();
    echo "Nota de débito creada: " . $document['payload']['id'];
    echo "Número de documento: " . $document['payload']['sri']['document_number'];
    echo "Documento de soporte: " . $document['payload']['support']['document_number'];
    echo "Total: $" . $document['payload']['total'];
} else {
    echo "Error: " . $response->body();
}

const axios = require('axios');

const createDebitNote = async () => {
    const token = 'your-api-token';

    const config = {
        method: 'post',
        url: 'https://dev-facturacion.e-dinky.test/api/v1/documents/create',
        headers: {
            'Content-Type': 'application/json',
            'Accept': 'application/json',
            'Authorization': `Bearer ${token}`
        },
        data: {
            sri_code_document: '05',
            send_to_emit: true,
            customer: {
                identification_number: '0123456789',
                name: 'Juan',
                lastname: 'Pérez',
                identification_type: 'CEDULA',
                email: '[email protected]',
                address: 'Quito, Ecuador'
            },
            document: {
                date: '2024-01-15',
                establishment: '001',
                point_of_emission: '001',
                support_code_document: '01',
                support_date: '2024-01-10',
                support_reason: 'Intereses por mora en el pago',
                support_document_number: '001-001-000000012'
            },
            items: [
                {
                    code: 'INT-001',
                    description: 'Intereses por mora - 30 días',
                    rate: 25.00,
                    quantity: 1,
                    subtotal: 25.00,
                    taxes: [
                        {
                            code: '2',
                            percentaje_code: '2',
                            percentaje_tax: 12,
                            total_tax: 3.00
                        }
                    ]
                }
            ]
        }
    };

    try {
        const response = await axios(config);
        console.log('Nota de débito creada:', response.data.payload.id);
        console.log('Número de documento:', response.data.payload.sri.document_number);
        console.log('Documento de soporte:', response.data.payload.support.document_number);
        console.log('Total: $', response.data.payload.total);
        return response.data;
    } catch (error) {
        console.error('Error:', error.response?.data || error.message);
        throw error;
    }
};

// Uso
createDebitNote()
    .then(result => console.log('Éxito:', result))
    .catch(error => console.error('Error:', error));

Tipos de Notas de Débito

1. Intereses por Mora

Cargos por pagos tardíos
Calculados según tasa acordada
Aplicables después del vencimiento
Motivo: “Intereses por mora”

2. Gastos de Cobranza

Costos administrativos de cobranza
Gastos legales o notariales
Comisiones de gestión
Motivo: “Gastos de cobranza”

3. Cargos Adicionales

Servicios no incluidos originalmente
Cambios en especificaciones
Servicios extras solicitados
Motivo: “Servicios adicionales”

4. Corrección de Errores

Errores en precios (al alza)
Cantidades incorrectas
Descuentos mal aplicados
Motivo: “Corrección de error”

5. Penalizaciones

Multas contractuales
Penalizaciones por incumplimiento
Cargos por daños
Motivo: “Penalización contractual”

6. Ajustes de Precio

Incrementos por inflación
Ajustes por tipo de cambio
Variaciones en costos
Motivo: “Ajuste de precio”

Motivos Comunes

Motivo	Descripción	Uso
`Intereses por mora`	Cargos por pagos tardíos	Morosidad
`Gastos de cobranza`	Costos administrativos	Gestión de cobranza
`Servicios adicionales`	Servicios no incluidos	Servicios extras
`Corrección de error`	Errores en datos o cálculos	Correcciones
`Penalización contractual`	Multas por incumplimiento	Penalizaciones
`Ajuste de precio`	Incrementos posteriores	Ajustes
`Cargo por financiamiento`	Costos financieros	Financiamiento
`Gastos administrativos`	Costos operativos	Administración

Validaciones Específicas

Documento de Soporte

Código: Debe corresponder a un tipo válido (01, 03, etc.)
Fecha: No puede ser posterior a la nota de débito
Número: Debe existir en el sistema
Motivo: Descripción clara y justificada

Cliente

Identificación: Debe coincidir con la factura original
Datos: Pueden ser actualizados si es necesario
Email: Requerido para notificaciones

Items (Cargos)

Códigos: Deben ser válidos en el catálogo
Descripciones: Claras y específicas
Montos: Justificados y razonables
Impuestos: Aplicación correcta según tipo

Totales

Subtotal: Suma correcta de items
Impuestos: Cálculo exacto según porcentajes
Total: Validación matemática precisa

Códigos de Respuesta

Código	Descripción	Acción
`201`	Nota de débito creada exitosamente	Continuar con el flujo
`400`	Datos inválidos	Revisar formato de datos
`401`	Token inválido	Renovar autenticación
`404`	Documento de soporte no encontrado	Verificar número de factura
`422`	Error de validación	Corregir datos según errores
`500`	Error del servidor	Reintentar más tarde

Errores Comunes

Error de Validación (422)

{
  "message": "Error de validación",
  "status": "UNPROCESSABLE_ENTITY",
  "errors": {
    "document.support_document_number": [
      "El documento de soporte no existe"
    ],
    "items.0.rate": [
      "El monto debe ser mayor a cero"
    ],
    "document.support_reason": [
      "El motivo es requerido"
    ]
  }
}

Soluciones

Documento de soporte no existe
- Verificar número de factura
- Confirmar que esté autorizada
- Revisar establecimiento y punto de emisión
Monto inválido
- Verificar que sea mayor a cero
- Confirmar formato numérico
- Validar cálculos de impuestos
Motivo requerido
- Proporcionar justificación clara
- Usar motivos estándar
- Incluir detalles específicos

Mejores Prácticas

1. Validación Previa

// Verificar factura original antes de crear nota de débito
$originalInvoice = $this->getInvoice($supportDocumentNumber);
if (!$originalInvoice || $originalInvoice->status !== 'authorized') {
    throw new InvalidSupportDocumentException();
}

2. Justificación de Cargos

// Validar que los cargos estén justificados
const validateCharges = (items, supportReason) => {
    items.forEach(item => {
        if (item.rate <= 0) {
            throw new InvalidChargeAmountError(item.code);
        }
        if (!item.description || item.description.length < 10) {
            throw new InsufficientDescriptionError(item.code);
        }
    });
};

3. Cálculo de Intereses

// Calcular intereses por mora automáticamente
$calculateInterest = function($originalAmount, $daysLate, $interestRate) {
    return ($originalAmount * $interestRate * $daysLate) / 365;
};

$interestAmount = $calculateInterest(1000, 30, 0.12); // 12% anual

4. Trazabilidad Completa

// Mantener referencia completa al documento original
const createDebitNote = (data) => {
    return {
        ...data,
        support: {
            document_id: originalInvoice.id,
            access_key: originalInvoice.access_key,
            original_amount: originalInvoice.total,
            ...data.support
        }
    };
};

Flujo Recomendado

Verificar factura original
- Confirmar que existe y está autorizada
- Validar datos del cliente
- Revisar estado de pagos
Justificar cargos
- Definir motivo específico y válido
- Calcular montos apropiados
- Documentar base legal o contractual
Preparar nota de débito
- Seleccionar códigos de cargos
- Calcular impuestos correctamente
- Validar información de soporte
Crear documento
- Enviar solicitud POST
- Verificar respuesta
- Manejar errores específicos
Procesar resultado
- Actualizar cuentas por cobrar
- Notificar al cliente
- Registrar en contabilidad

Consideraciones Legales

Requisitos Contractuales

Base legal: Los cargos deben estar respaldados por contrato
Notificación previa: Algunos cargos requieren notificación
Límites: Respetar límites legales de intereses
Documentación: Mantener evidencia de la justificación

Plazos y Términos

Vencimiento: Respetar plazos contractuales
Notificación: Informar oportunamente al cliente
Disputa: Procedimiento para objeciones
Prescripción: Considerar plazos de prescripción

Impacto Contable

En el Emisor

Ingresos: Aumento en ingresos por cargos
IVA: Incremento en IVA por pagar
Cuentas por cobrar: Aumento del saldo
Intereses: Registro de ingresos financieros

En el Cliente

Gastos: Aumento en gastos o costos
IVA: Incremento en crédito tributario
Cuentas por pagar: Aumento del saldo
Intereses: Registro de gastos financieros

Casos de Uso Específicos

1. Intereses por Mora

{
  "items": [
    {
      "code": "INT-MORA",
      "description": "Intereses por mora - Factura 001-001-000000012 - 30 días",
      "rate": 45.50,
      "quantity": 1,
      "subtotal": 45.50
    }
  ]
}

2. Gastos de Cobranza

{
  "items": [
    {
      "code": "GASTO-COB",
      "description": "Gastos administrativos de cobranza",
      "rate": 25.00,
      "quantity": 1,
      "subtotal": 25.00
    }
  ]
}

3. Servicios Adicionales

{
  "items": [
    {
      "code": "SERV-EXTRA",
      "description": "Instalación adicional no incluida",
      "rate": 150.00,
      "quantity": 1,
      "subtotal": 150.00
    }
  ]
}

Notas Importantes

📋 Documento de soporte obligatorio: Toda nota de débito debe referenciar un documento válido
⚖️ Justificación legal: Los cargos deben estar respaldados contractual o legalmente
🔗 Trazabilidad completa: Se mantiene la relación con el documento original
⏰ Plazos apropiados: Respetar términos contractuales y legales
📧 Notificaciones automáticas: El cliente recibe notificación de la nota de débito
💾 Impacto en reportes: Afecta automáticamente los reportes del SRI
🔄 Estados sincronizados: El estado se actualiza automáticamente
📊 Contabilización automática: Se registra automáticamente en la contabilidad
🚫 No modificable: Una vez autorizada, no se puede modificar
💰 Límites de intereses: Respetar límites legales para tasas de interés