Notas de Crédito

Pruebas
Producción

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

Las notas de crédito son documentos electrónicos que se utilizan para anular total o parcialmente una factura, realizar devoluciones, aplicar descuentos posteriores a la venta, o corregir errores en documentos previamente emitidos.

Información General

Código SRI: 04
Tipo de documento: Nota de Crédito
Uso: Anulaciones, devoluciones, descuentos, correcciones
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 `"04"` para notas de crédito
`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 productos/servicios a acreditar
`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": "Devolución de mercadería",
  "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 crédito	`"Devolución de mercadería"`
`support_document_number`	Número del documento original	`"001-001-000000012"`

Ejemplos de Implementación

Nota de Crédito Simple

Solicitud

{
  "sri_code_document": "04",
  "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": "Devolución de mercadería defectuosa",
    "support_document_number": "001-001-000000012"
  },
  "items": [
    {
      "code": "PROD-001",
      "description": "Producto devuelto",
      "rate": 10.00,
      "quantity": 1,
      "subtotal": 10.00,
      "taxes": [
        {
          "code": "2",
          "percentaje_code": "2",
          "percentaje_tax": 12,
          "total_tax": 1.20
        }
      ]
    }
  ]
}

Respuesta Exitosa (201)

{
  "message": "Documento creado exitosamente",
  "status": "CREATED",
  "payload": {
    "id": 123456789,
    "environment": "PROD",
    "number": 1,
    "date": "2024-01-15",
    "subtotal": "10.00",
    "tax_amount": "1.20",
    "total": "11.20",
    "type": "credit_note",
    "customer": {
      "id": 987654321,
      "full_name": "Juan Pérez",
      "email": "[email protected]",
      "identification_type": "cedula",
      "identification_number": "0123456789"
    },
    "sri": {
      "access_key": "1501202404012345678900110010010000000011234567890",
      "status": "AUTORIZADO",
      "sequential_number": "000000001",
      "establishment": "001",
      "point_emission": "001",
      "document_number": "001-001-000000001",
      "type_document": "NOTA CREDITO",
      "code_document": "04"
    },
    "support": {
      "code_document": "01",
      "document_number": "001-001-000000012",
      "date": "2024-01-10",
      "reason": "Devolución de mercadería defectuosa"
    },
    "items": [
      {
        "position": 1,
        "code": "PROD-001",
        "description": "Producto devuelto",
        "rate": "10.00",
        "quantity": "1.00",
        "subtotal": "10.00",
        "total_tax": "1.20",
        "total": "11.20"
      }
    ]
  }
}

Nota de Crédito con ICE e IVA

Solicitud

{
  "sri_code_document": "04",
  "customer": {
    "identification_number": "9999999999",
    "name": "Final",
    "lastname": "Consumidor",
    "identification_type": "CEDULA",
    "email": "[email protected]",
    "address": "Guayaquil"
  },
  "document": {
    "date": "2024-10-09",
    "sri_establishment": "001",
    "sri_point_emi": "004",
    "support_code_document": "01",
    "support_date": "2024-10-09",
    "support_reason": "Devolución de mercadería",
    "support_document_number": "001-001-000000012"
  },
  "items": [
    {
      "code": "ICE-001",
      "description": "ITEM PRUEBAS ICE 2",
      "rate": 100,
      "quantity": 1,
      "subtotal": 100,
      "total_tax": 26.5,
      "total": 126.5,
      "taxes": [
        {
          "code": "3",
          "percentaje_code": "3053",
          "percentaje_tax": 10,
          "total_tax": 10
        },
        {
          "code": "2",
          "percentaje_code": "4",
          "percentaje_tax": 15,
          "total_tax": 16.50
        }
      ]
    }
  ],
  "aditional_fields": [
    {
      "key": "Telefono",
      "value": "099999",
      "type": "sri"
    },
    {
      "key": "Email",
      "value": "[email protected]",
      "type": "sri"
    }
  ]
}

Respuesta con ICE e IVA (201)

{
  "message": "Documento creado",
  "status": "CREATED",
  "payload": {
    "id": 1339329970,
    "environment": "TEST",
    "number": 3,
    "date": "2024-10-09",
    "subtotal": "200.00",
    "tax_amount": "53.00",
    "total": "253.00",
    "status": "draft",
    "type": "credit_note",
    "customer": {
      "id": 61247344,
      "full_name": "Consumidor Final",
      "email": "[email protected]",
      "identification_type": "cedula",
      "identification_number": "9999999999"
    },
    "sri": {
      "establishment": "001",
      "point_emi": "004",
      "type_document": "NOTA CREDITO",
      "title_document": "Nota de crédito",
      "code_document": "04"
    },
    "support": {
      "code_document": "01",
      "document_number": "001-001-000000012",
      "date": "2024-10-09",
      "reason": "Devolución de mercadería"
    },
    "items": [
      {
        "position": 1,
        "code": "ICE-001",
        "description": "ITEM PRUEBAS ICE 2",
        "rate": "100.00",
        "quantity": "1.00",
        "subtotal": "100.00",
        "total_tax": "26.50",
        "total": "126.50",
        "taxes": [
          {
            "type": "ICE",
            "name": "ICE Bebidas Gaseosas con Alto Contenido de Azúcar",
            "code": "3",
            "percentaje_code": "3053",
            "rate_before_tax": "100.00",
            "percentaje_tax": "10.00",
            "total_tax": "10.00",
            "rate_after_tax": "110.00"
          },
          {
            "type": "IVA",
            "name": "15%",
            "code": "2",
            "percentaje_code": "4",
            "rate_before_tax": "110.00",
            "percentaje_tax": "15.00",
            "total_tax": "16.50",
            "rate_after_tax": "126.50"
          }
        ]
      }
    ],
    "taxes": [
      {
        "tax_type": "ICE",
        "tax_name": "ICE Bebidas Gaseosas con Alto Contenido de Azúcar",
        "tax_rate": "20.00",
        "tax_subtotal": "200.00",
        "tax_code": "3",
        "tax_code_sri": "3053"
      },
      {
        "tax_type": "IVA",
        "tax_name": "15%",
        "tax_rate": "33.00",
        "tax_subtotal": "220.00",
        "tax_code": "2",
        "tax_code_sri": "4"
      }
    ]
  }
}

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": "04",
    "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": "Devolución de mercadería defectuosa",
      "support_document_number": "001-001-000000012"
    },
    "items": [
      {
        "code": "PROD-001",
        "description": "Producto devuelto",
        "rate": 10.00,
        "quantity": 1,
        "subtotal": 10.00,
        "taxes": [
          {
            "code": "2",
            "percentaje_code": "2",
            "percentaje_tax": 12,
            "total_tax": 1.20
          }
        ]
      }
    ]
  }'

<?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' => '04',
    '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' => 'Devolución de mercadería defectuosa',
        'support_document_number' => '001-001-000000012'
    ],
    'items' => [
        [
            'code' => 'PROD-001',
            'description' => 'Producto devuelto',
            'rate' => 10.00,
            'quantity' => 1,
            'subtotal' => 10.00,
            'taxes' => [
                [
                    'code' => '2',
                    'percentaje_code' => '2',
                    'percentaje_tax' => 12,
                    'total_tax' => 1.20
                ]
            ]
        ]
    ]
]);

if ($response->successful()) {
    $document = $response->json();
    echo "Nota de crédito 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 createCreditNote = 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: '04',
            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: 'Devolución de mercadería defectuosa',
                support_document_number: '001-001-000000012'
            },
            items: [
                {
                    code: 'PROD-001',
                    description: 'Producto devuelto',
                    rate: 10.00,
                    quantity: 1,
                    subtotal: 10.00,
                    taxes: [
                        {
                            code: '2',
                            percentaje_code: '2',
                            percentaje_tax: 12,
                            total_tax: 1.20
                        }
                    ]
                }
            ]
        }
    };

    try {
        const response = await axios(config);
        console.log('Nota de crédito 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
createCreditNote()
    .then(result => console.log('Éxito:', result))
    .catch(error => console.error('Error:', error));

Tipos de Notas de Crédito

1. Anulación Total

Cancela completamente una factura
Debe incluir todos los items de la factura original
Mismos impuestos y valores
Motivo: “Anulación de factura”

2. Anulación Parcial

Cancela solo algunos items de la factura
Items específicos con cantidades exactas
Cálculo proporcional de impuestos
Motivo: “Anulación parcial”

3. Devolución

Por productos defectuosos o no conformes
Requiere verificación de inventario
Puede incluir gastos de transporte
Motivo: “Devolución de mercadería”

4. Descuento Posterior

Descuentos aplicados después de la venta
Por promociones o acuerdos comerciales
No afecta inventario
Motivo: “Descuento comercial”

5. Corrección de Errores

Para corregir errores en precios o cantidades
Debe especificar claramente el error
Requiere nueva factura si es necesario
Motivo: “Corrección de error”

Motivos Comunes

Motivo	Descripción	Uso
`Anulación de factura`	Cancelación total del documento	Anulación completa
`Devolución de mercadería`	Productos devueltos por el cliente	Devoluciones
`Descuento comercial`	Descuentos posteriores a la venta	Promociones
`Corrección de error`	Errores en datos o cálculos	Correcciones
`Producto defectuoso`	Mercadería con defectos	Garantías
`Cancelación de servicio`	Servicios no prestados	Servicios
`Ajuste de precio`	Corrección de precios	Ajustes

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 crédito
Número: Debe existir en el sistema
Motivo: Descripción clara y específica

Cliente

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

Items

Códigos: Deben existir en la factura original
Cantidades: No pueden exceder las facturadas
Precios: Deben coincidir con los originales
Impuestos: Mismos códigos y porcentajes

Totales

Subtotal: No puede exceder el de la factura
Impuestos: Cálculo proporcional correcto
Total: Validación matemática exacta

Códigos de Respuesta

Código	Descripción	Acción
`201`	Nota de crédito 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.quantity": [
      "La cantidad excede la facturada"
    ],
    "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
Cantidad excede la facturada
- Consultar factura original
- Verificar cantidades disponibles
- Considerar notas de crédito previas
Motivo requerido
- Proporcionar descripció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 crédito
$originalInvoice = $this->getInvoice($supportDocumentNumber);
if (!$originalInvoice || $originalInvoice->status !== 'authorized') {
    throw new InvalidSupportDocumentException();
}

2. Control de Cantidades

// Validar cantidades disponibles
const validateQuantities = (originalItems, creditItems) => {
    creditItems.forEach(creditItem => {
        const originalItem = originalItems.find(item => item.code === creditItem.code);
        if (!originalItem || creditItem.quantity > originalItem.available_quantity) {
            throw new ExceededQuantityError(creditItem.code);
        }
    });
};

3. Cálculo de Impuestos

// Mantener mismos impuestos que la factura original
$creditNote->items->each(function($item) use ($originalInvoice) {
    $originalItem = $originalInvoice->items->where('code', $item->code)->first();
    $item->taxes = $originalItem->taxes;
});

4. Trazabilidad

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

Flujo Recomendado

Verificar factura original
- Confirmar que existe y está autorizada
- Validar datos del cliente
- Revisar items disponibles
Preparar nota de crédito
- Definir motivo específico
- Seleccionar items a acreditar
- Calcular cantidades y totales
Validar datos
- Verificar cantidades no excedan las originales
- Confirmar cálculos de impuestos
- Validar información de soporte
Crear documento
- Enviar solicitud POST
- Verificar respuesta
- Manejar errores específicos
Procesar resultado
- Actualizar inventario si aplica
- Notificar al cliente
- Registrar en contabilidad

Impacto Contable

En el Emisor

Ventas: Reducción en ingresos
IVA: Disminución en IVA por pagar
Inventario: Aumento si hay devolución física
Cuentas por cobrar: Reducción del saldo

En el Cliente

Compras: Reducción en gastos
IVA: Disminución en crédito tributario
Inventario: Reducción si hay devolución
Cuentas por pagar: Reducción del saldo

Notas Importantes

📋 Documento de soporte obligatorio: Toda nota de crédito debe referenciar un documento válido
🔗 Trazabilidad completa: Se mantiene la relación con el documento original
⏰ Plazo de emisión: Debe emitirse dentro del período fiscal correspondiente
📧 Notificaciones automáticas: El cliente recibe notificación de la nota de crédito
💾 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