> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cucu.bo/llms.txt
> Use this file to discover all available pages before exploring further.

# Nota Credito-Debito

> Documento de ajuste fiscal para devoluciones parciales o totales sobre facturas emitidas. Sectores 24, 47 (Descuento) y 48 (ICE).

Documento de ajuste que permite corregir o anular parcialmente una factura ya emitida. Obligatorio para devoluciones despues de 30 dias de la emision original.

## Datos del sector

| Campo        | Valor                                         |
| ------------ | --------------------------------------------- |
| Sector SIAT  | `24` (estandar), `47` (Descuento), `48` (ICE) |
| WSDL SIAT    | `ServicioFacturacionDocumentoAjuste`          |
| Tipo interno | `NOTE_CREDIT_DEBIT`                           |

### Variantes por `documentSectorType`

El campo opcional `documentSectorType` en el body selecciona la variante de la nota:

| Sector | Tipo                                   | Cuando usarlo                                                          |
| ------ | -------------------------------------- | ---------------------------------------------------------------------- |
| `24`   | Nota Credito-Debito estandar (default) | Devoluciones/ajustes normales                                          |
| `47`   | Nota Credito-Debito **Descuento**      | La factura original tenia descuento adicional prorrateado por item     |
| `48`   | Nota Credito-Debito **ICE**            | La factura original tenia productos con Impuesto al Consumo Especifico |

<Warning>
  **Nunca re-envies las lineas originales.** En los tres sectores, las lineas de la factura original
  (`codigoDetalleTransaccion=1`) se **clonan desde la base de datos** y espejan exacto lo registrado
  en SIAT. Solo mandas los items devueltos en `returnedDetails`. El sector `48` es la unica excepcion:
  acepta un overlay minimal en `originalDetails` **solo** para los datos ICE (`nroItem` + `marcaIce` +
  montos ICE), porque la compra-venta original no los almacena. Detalle completo en
  [Crear Nota Credito/Debito](/api/credit-note#notas-descuento-e-ice-sectores-47-y-48).
</Warning>

## Endpoint dedicado

Las notas de credito/debito se crean a partir de una factura original existente usando un endpoint dedicado:

```
POST /api/v1/invoices/{originalInvoiceId}/credit-note
```

<Info>
  A diferencia de otros documentos sector, las notas **no** se crean via `POST /api/v1/invoices`.
  Usa el endpoint dedicado que obtiene automaticamente los datos de la factura original (cliente, CUF, montos, items).
</Info>

Ver la referencia completa del endpoint en [Crear Nota Credito/Debito](/api/credit-note).

## Como funciona

1. Envias el UUID de la factura original en la URL + los items devueltos en el body
2. El sistema obtiene automaticamente los datos de la factura original
3. Los items se separan en dos tablas: originales (`codigoDetalleTransaccion=1`, clonados desde la BD) y devueltos (`codigoDetalleTransaccion=2`, del request)
4. Se calculan montos automaticamente: `montoTotalOriginal`, `montoTotalDevuelto`, `montoDescuentoCreditoDebito`, `montoEfectivoCreditoDebito`
5. La nota se valida contra el SIAT via `ServicioFacturacionDocumentoAjuste`
6. Se genera PDF dedicado (con dos tablas: items originales + items devueltos) y se envia email

## Campos del SIAT (sector 24)

Estos campos se calculan automaticamente por el sistema. Se documentan aqui como referencia del XML que se envia al SIAT:

### Cabecera

| Campo XML                     | Descripcion                                                        |
| ----------------------------- | ------------------------------------------------------------------ |
| `numeroAutorizacionCuf`       | CUF de la factura original                                         |
| `numeroFactura` (original)    | Numero de la factura original                                      |
| `fechaEmision` (original)     | Fecha de emision de la factura original                            |
| `montoTotalOriginal`          | Suma de subtotales de items originales (antes de descuento global) |
| `montoTotalSujetoIva`         | Monto total devuelto sujeto a IVA                                  |
| `montoDescuentoCreditoDebito` | Descuento proporcional aplicado en la nota                         |
| `montoEfectivoCreditoDebito`  | 13% IVA sobre el monto devuelto                                    |

### Detalle

| Campo XML                  | Valor | Descripcion                 |
| -------------------------- | ----- | --------------------------- |
| `codigoDetalleTransaccion` | `1`   | Item de la factura original |
| `codigoDetalleTransaccion` | `2`   | Item devuelto/ajustado      |

## Ejemplo rapido

<CodeGroup>
  ```bash cURL theme={"system"}
  curl -X POST "https://sandbox.cucu.bo/api/v1/invoices/ORIGINAL_INVOICE_UUID/credit-note" \
    -H "Content-Type: application/json" \
    -H "X-API-Key: YOUR_API_KEY" \
    -d '{
      "pointOfSaleId": "660e8400-e29b-41d4-a716-446655440004",
      "notaType": "CREDITO",
      "paymentMethodCode": 1,
      "returnedDetails": [
        {
          "activityEconomic": "620100",
          "codeProductSin": "83141",
          "description": "Devolucion parcial - Servicio de software",
          "quantity": 1,
          "unitMeasure": 58,
          "priceUnit": 200.00
        }
      ]
    }'
  ```

  ```javascript JavaScript theme={"system"}
  const response = await fetch(
    'https://sandbox.cucu.bo/api/v1/invoices/ORIGINAL_INVOICE_UUID/credit-note',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': 'YOUR_API_KEY'
      },
      body: JSON.stringify({
        pointOfSaleId: '660e8400-e29b-41d4-a716-446655440004',
        notaType: 'CREDITO',
        paymentMethodCode: 1,
        returnedDetails: [{
          activityEconomic: '620100',
          codeProductSin: '83141',
          description: 'Devolucion parcial - Servicio de software',
          quantity: 1,
          unitMeasure: 58,
          priceUnit: 200.00
        }]
      })
    }
  );
  ```

  ```python Python theme={"system"}
  import requests

  response = requests.post(
      'https://sandbox.cucu.bo/api/v1/invoices/ORIGINAL_INVOICE_UUID/credit-note',
      headers={
          'Content-Type': 'application/json',
          'X-API-Key': 'YOUR_API_KEY'
      },
      json={
          'pointOfSaleId': '660e8400-e29b-41d4-a716-446655440004',
          'notaType': 'CREDITO',
          'paymentMethodCode': 1,
          'returnedDetails': [{
              'activityEconomic': '620100',
              'codeProductSin': '83141',
              'description': 'Devolucion parcial - Servicio de software',
              'quantity': 1,
              'unitMeasure': 58,
              'priceUnit': 200.00
          }]
      }
  )
  ```
</CodeGroup>

## Anular una nota

Para anular una nota de credito/debito emitida:

```
POST /api/v1/invoices/{noteId}/cancel-note?motivo=1
```

Ver [Anular Nota Credito/Debito](/api/cancel-note) para la referencia completa.

<Warning>
  La factura original debe estar en estado `VALIDATED`. No se puede emitir una nota sobre una factura rechazada o ya anulada.
</Warning>

<Warning>
  Si la factura original usa `montoGiftCard > 0`, el `paymentMethodCode` debe incluir `27` (Gift Card). Error SIAT 1050 si se omite.
</Warning>