# Nota de débito electrónica

<p class="callout info">**Endpoint**  
*PUT* /api/2.0/documentos-electronicos/emision/nota-debito/{clave}</p>

Emite una nota de débito electrónica con la disposición 4.4 sobre un documento ya emitido, para incrementar el monto de una operación previamente facturada. Al igual que la nota de crédito, este endpoint usa el método **PUT** y la clave del documento de referencia viaja en la URL, no en el cuerpo.

<p class="callout warning">La nota de débito **hereda al receptor, la moneda y el tipo de cambio del documento de referencia**. Esos campos se ignoran si se envían en el cuerpo. Ver la sección «Datos heredados».</p>

## Autenticación

Todas las peticiones requieren los cuatro encabezados siguientes.

<table id="bkmrk-encabezadodescripci%C3%B3"><thead><tr><th>Encabezado</th><th>Descripción</th></tr></thead><tbody><tr><td>`api-token`</td><td>Token de API de la cuenta.</td></tr><tr><td>`access-token`</td><td>Token de acceso asociado al `api-token`.</td></tr><tr><td>`Content-Type`</td><td>`application/json`</td></tr><tr><td>`Accept`</td><td>`application/json`. **Obligatorio.** Si se omite, una petición no autenticada responde con una redirección al formulario de inicio de sesión en lugar de un error JSON.</td></tr></tbody></table>

La emisión por API requiere un plan con acceso a API activo y documentos disponibles en el ciclo vigente.

## Documento de referencia

El segmento `{clave}` de la URL es la **clave numérica de 50 dígitos** del documento sobre el que se emite la nota. El documento debe pertenecer a la misma cuenta que emite la nota; no es posible referenciar comprobantes de otro contribuyente.

```text
PUT /api/2.0/documentos-electronicos/emision/nota-debito/50622032000070175094601000001010000000006118491223
```

## Ejemplo mínimo

```shell
curl --location --request PUT 'https://app.facturadorvirtual.com/api/2.0/documentos-electronicos/emision/nota-debito/50622032000070175094601000001010000000006118491223' \
--header 'api-token: iuJPbVCYQY3AmWuVHMflT9ZySlwzxb9ehviLbHNsz6yQnBm4' \
--header 'access-token: IDq4ME4ZUO9YmQ0fOc43AFp7mMO6talIuIALFaUUcs2H2pwLpYN2' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "actividad": "014002",
    "razon": "03",
    "razon_referencia": "Por corrección de monto",
    "condicion_venta": "01",
    "medio_pago": {
        "01": {
            "codigo": "01",
            "total": 565
        }
    },
    "comentarios": "Ajuste al alza sobre la factura de referencia",
    "lineas": [
        {
            "codigo": "00001",
            "codigoCabys": "0196109000000",
            "descripcion": "Diferencia de precio Entrada a CRFW22",
            "cantidad": "1",
            "unidad": "Unid",
            "descuento": 0,
            "naturalezaDescuento": "",
            "precioUnitario": 500,
            "impuestos": {
                "01": {
                    "tarifa": "08"
                }
            }
        }
    ]
}'
```

## Datos heredados del documento de referencia

Los siguientes datos se toman del documento referenciado y **no se leen del cuerpo de la petición**. Enviarlos no produce error, pero tampoco tiene efecto.

<table id="bkmrk-datoorigen-identific"><thead><tr><th>Dato</th><th>Origen</th></tr></thead><tbody><tr><td>Identificación, tipo de identificación, nombre, nombre comercial, teléfono y correo del receptor</td><td>Documento de referencia</td></tr><tr><td>Ubicación del receptor (provincia, cantón, distrito, barrio, otras señas)</td><td>Documento de referencia, si lo tenía registrado</td></tr><tr><td>`moneda`</td><td>Resumen del documento de referencia</td></tr><tr><td>`tipo_cambio`</td><td>Resumen del documento de referencia</td></tr></tbody></table>

Por esa razón los campos `cedula`, `tipo_cedula`, `nombre`, `correo`, `telefono`, `moneda` y `tipo_cambio` no aparecen entre los campos aceptados de este endpoint.

## Campos del documento

### Obligatorios

<table id="bkmrk-campotipodescripci%C3%B3n"><thead><tr><th>Campo</th><th>Tipo</th><th>Descripción</th></tr></thead><tbody><tr><td>`actividad`</td><td>string</td><td>Código de la actividad económica del emisor. Debe estar registrada en la cuenta.</td></tr><tr><td>`razon`</td><td>string</td><td>Código de la razón de la nota. Ver la tabla y la advertencia más abajo.</td></tr><tr><td>`medio_pago`</td><td>object</td><td>De 1 a 4 medios de pago. Se ignora cuando la condición de venta es a crédito.</td></tr><tr><td>`lineas`</td><td>array</td><td>Al menos una línea de detalle. Ver la sección correspondiente.</td></tr></tbody></table>

### Opcionales

<table id="bkmrk-campotipodescripci%C3%B3n-1"><thead><tr><th>Campo</th><th>Tipo</th><th>Descripción</th></tr></thead><tbody><tr><td>`condicion_venta`</td><td>string</td><td>Código de condición de venta de la nota. Ver la tabla más abajo.</td></tr><tr><td>`razon_referencia`</td><td>string</td><td>Descripción de la razón. Si se omite, se usa el texto correspondiente al código enviado en `razon`.</td></tr><tr><td>`sin_receptor`</td><td>boolean</td><td>Con valor verdadero, la nota se emite **sin datos del receptor**, aunque el documento de referencia los tuviera.</td></tr><tr><td>`codigo_actividad_receptor`</td><td>string</td><td>Código de actividad económica del receptor.</td></tr><tr><td>`sucursal`</td><td>string</td><td>Código de sucursal, por ejemplo `004`. Si se omite, se usa el valor configurado en las preferencias de facturación.</td></tr><tr><td>`punto`</td><td>string</td><td>Punto de emisión, por ejemplo `00001`. Si se omite, se usa el valor configurado en las preferencias de facturación.</td></tr><tr><td>`comentarios`</td><td>string</td><td>Notas del comprobante. Si el texto contiene un patrón `#codigo`, ese valor se registra además como número de orden.</td></tr><tr><td>`orden`</td><td>string u object</td><td>Número de orden asociado. Acepta un string con el código, o un objeto `{"codigo": "...", "estado": "...", "proveedor": "..."}`.</td></tr><tr><td>`devolucion`</td><td>number</td><td>Monto de devolución de IVA, mayor que cero.</td></tr><tr><td>`cargos`</td><td>array</td><td>Otros cargos del comprobante.</td></tr></tbody></table>

### Campos condicionales

<table id="bkmrk-campose-vuelve-oblig"><thead><tr><th>Campo</th><th>Se vuelve obligatorio cuando…</th><th>Reglas</th></tr></thead><tbody><tr><td>`plazo_credito`</td><td>`condicion_venta` es `02` o `10`</td><td>Entero entre 1 y 99999, expresado en días.</td></tr><tr><td>`condicion_venta_otros`</td><td>`condicion_venta` es `99`</td><td>Texto entre 5 y 100 caracteres.</td></tr><tr><td>`medio_pago.<codigo>.detalle`</td><td>El código del medio de pago es `99`</td><td>Texto entre 3 y 100 caracteres.</td></tr></tbody></table>

## Razón de la nota

<table id="bkmrk-c%C3%B3digodescripci%C3%B3n-01"><thead><tr><th>Código</th><th>Descripción</th></tr></thead><tbody><tr><td>`01`</td><td>Para anular documento de referencia</td></tr><tr><td>`02`</td><td>Por corrección de texto</td></tr><tr><td>`03`</td><td>Por corrección de monto</td></tr></tbody></table>

Solo se aceptan los tres códigos de la tabla; cualquier otro valor se rechaza con `422`. Si se omite `razon_referencia`, la descripción se toma del catálogo de razones de la nota de débito.

## Condición de venta

<table id="bkmrk-c%C3%B3digodescripci%C3%B3n-01-1"><thead><tr><th>Código</th><th>Descripción</th></tr></thead><tbody><tr><td>`01`</td><td>Contado</td></tr><tr><td>`02`</td><td>Crédito</td></tr><tr><td>`03`</td><td>Consignación</td></tr><tr><td>`04`</td><td>Apartado</td></tr><tr><td>`05`</td><td>Arrendamiento con opción de compra</td></tr><tr><td>`06`</td><td>Arrendamiento en función financiera</td></tr><tr><td>`07`</td><td>Cobro a favor de un tercero</td></tr><tr><td>`08`</td><td>Servicios prestados al Estado</td></tr><tr><td>`09`</td><td>Pago de servicios prestados al Estado</td></tr><tr><td>`10`</td><td>Venta a crédito en IVA hasta 90 días</td></tr><tr><td>`11`</td><td>Pago de venta a crédito en IVA hasta 90 días</td></tr><tr><td>`12`</td><td>Venta de mercancía no nacionalizada</td></tr><tr><td>`13`</td><td>Venta de bienes usados no contribuyente</td></tr><tr><td>`14`</td><td>Arrendamiento operativo</td></tr><tr><td>`15`</td><td>Arrendamiento financiero</td></tr><tr><td>`99`</td><td>Otros. Requiere `condicion_venta_otros`.</td></tr></tbody></table>

<p class="callout warning">Con las condiciones de venta `02`, `08` y `10` el comprobante se emite a crédito y **los medios de pago enviados se descartan**: el XML no incluye el nodo de medio de pago. Aun así el campo `medio_pago` debe venir presente en la petición.</p>

## Medios de pago

`medio_pago` es un objeto con hasta cuatro entradas, donde la clave y el campo `codigo` coinciden. `total` es el monto cubierto por ese medio y debe ser mayor que cero.

```json
"medio_pago": {
    "01": { "codigo": "01", "total": 130 },
    "02": { "codigo": "02", "total": 400 },
    "03": { "codigo": "03", "total": 600 }
}
```

<table id="bkmrk-c%C3%B3digodescripci%C3%B3n-01-2"><thead><tr><th>Código</th><th>Descripción</th></tr></thead><tbody><tr><td>`01`</td><td>Efectivo</td></tr><tr><td>`02`</td><td>Tarjeta</td></tr><tr><td>`03`</td><td>Cheque</td></tr><tr><td>`04`</td><td>Transferencia o depósito bancario</td></tr><tr><td>`05`</td><td>Recaudado por terceros</td></tr><tr><td>`06`</td><td>SINPE Móvil</td></tr><tr><td>`07`</td><td>Plataforma digital</td></tr><tr><td>`99`</td><td>Otros. Requiere `detalle`.</td></tr></tbody></table>

## Líneas de detalle

### Campos obligatorios de la línea

<table id="bkmrk-campotipodescripci%C3%B3n-2"><thead><tr><th>Campo</th><th>Tipo</th><th>Descripción</th></tr></thead><tbody><tr><td>`codigo`</td><td>string</td><td>Código del producto o servicio, máximo 20 caracteres.</td></tr><tr><td>`descripcion`</td><td>string</td><td>Detalle de la línea, entre 3 y 200 caracteres.</td></tr><tr><td>`cantidad`</td><td>number</td><td>Cantidad, mayor que cero. Se redondea a 3 decimales.</td></tr><tr><td>`unidad`</td><td>string</td><td>Código de unidad de medida del catálogo de Hacienda. Debe coincidir exactamente con un código del catálogo, por ejemplo `Unid`, `Sp`, `Os`, `Kg`, `L`, `Al`, `Alc`.</td></tr><tr><td>`precioUnitario`</td><td>number</td><td>Precio unitario, mayor o igual a cero.</td></tr><tr><td>`descuento`</td><td>number</td><td>Monto del descuento. Envíe `0` si no aplica.</td></tr><tr><td>`naturalezaDescuento`</td><td>string</td><td>Naturaleza del descuento. Envíe cadena vacía si no aplica; si se envía texto, debe tener entre 3 y 80 caracteres.</td></tr></tbody></table>

<p class="callout danger">`codigoCabys` no es rechazado por la validación, pero Hacienda exige el código CABYS en todos los comprobantes. Omitirlo produce un rechazo del lado de Hacienda, no del API.</p>

### Campos opcionales de la línea

<table id="bkmrk-campotipodescripci%C3%B3n-3"><thead><tr><th>Campo</th><th>Tipo</th><th>Descripción</th></tr></thead><tbody><tr><td>`codigoCabys`</td><td>string</td><td>Código CABYS de 13 dígitos.</td></tr><tr><td>`codigoInternoFV`</td><td>string</td><td>Código del producto en el catálogo de Facturador Virtual.</td></tr><tr><td>`id_producto`</td><td>integer</td><td>Identificador del producto en Facturador Virtual.</td></tr><tr><td>`unidadMedidaComercial`</td><td>string</td><td>Unidad de medida comercial, máximo 20 caracteres.</td></tr><tr><td>`partidaArancelaria`</td><td>string</td><td>Partida arancelaria de la mercancía.</td></tr><tr><td>`tipoTransaccion`</td><td>string</td><td>Código de tipo de transacción de la versión 4.4.</td></tr><tr><td>`tipoDescuento`</td><td>string</td><td>Código del tipo de descuento, máximo 2 caracteres. Si se omite se asume `08`. Con los códigos `01` y `03` el impuesto de la línea se registra como asumido por el emisor.</td></tr><tr><td>`tipoDescuentoOtro`</td><td>string</td><td>Descripción cuando `tipoDescuento` corresponde a «otros». Entre 5 y 100 caracteres.</td></tr><tr><td>`ivaCobradoFabrica`</td><td>number</td><td>IVA cobrado en fábrica.</td></tr><tr><td>`vinSerie`</td><td>string</td><td>Número VIN o serie, para vehículos.</td></tr><tr><td>`esCabysMedicamento`</td><td>boolean</td><td>Marca la línea como medicamento. Al activarse se toman `registroMedicamento` (máximo 100 caracteres) y `formaFarmaceutica` (3 caracteres).</td></tr><tr><td>`es_combo`</td><td>boolean</td><td>Marca la línea como combo. Los componentes se envían en `componentes`, un arreglo con la misma estructura de una línea de detalle.</td></tr><tr><td>`impuestos`</td><td>object</td><td>Impuestos aplicados a la línea. Ver la siguiente sección.</td></tr></tbody></table>

## Impuestos

`impuestos` es un objeto cuya clave es el código del impuesto. El campo `tarifa` recibe el **código de tarifa**, no el porcentaje: el porcentaje se resuelve a partir de ese código.

```json
"impuestos": {
    "01": {
        "tarifa": "08"
    }
}
```

<table id="bkmrk-c%C3%B3digo-de-impuestode"><thead><tr><th>Código de impuesto</th><th>Descripción</th></tr></thead><tbody><tr><td>`01`</td><td>Impuesto al Valor Agregado</td></tr><tr><td>`02`</td><td>Impuesto Selectivo de Consumo</td></tr><tr><td>`03`</td><td>Impuesto Único a los Combustibles</td></tr><tr><td>`04`</td><td>Impuesto específico de Bebidas Alcohólicas</td></tr><tr><td>`05`</td><td>Impuesto Específico sobre las bebidas envasadas sin contenido alcohólico y jabones de tocador</td></tr><tr><td>`06`</td><td>Impuesto a los Productos de Tabaco</td></tr><tr><td>`07`</td><td>IVA (cálculo especial)</td></tr><tr><td>`08`</td><td>IVA Régimen de Bienes Usados (Factor)</td></tr><tr><td>`12`</td><td>Impuesto Específico al Cemento</td></tr><tr><td>`99`</td><td>Otros. Se describe en `descripcionOtro`.</td></tr></tbody></table>

<table id="bkmrk-c%C3%B3digo-de-tarifadesc"><thead><tr><th>Código de tarifa</th><th>Descripción</th><th>Porcentaje aplicado</th></tr></thead><tbody><tr><td>`01`</td><td>Tarifa 0% (Artículo 32, num 1, RLIVA)</td><td>0</td></tr><tr><td>`02`</td><td>Tarifa reducida 1%</td><td>1</td></tr><tr><td>`03`</td><td>Tarifa reducida 2%</td><td>2</td></tr><tr><td>`04`</td><td>Tarifa reducida 4%</td><td>4</td></tr><tr><td>`05`</td><td>Transitorio 0%</td><td>0</td></tr><tr><td>`06`</td><td>Transitorio 4%</td><td>4</td></tr><tr><td>`07`</td><td>Tarifa transitoria 8%</td><td>8</td></tr><tr><td>`08`</td><td>Tarifa general 13%</td><td>13</td></tr><tr><td>`09`</td><td>Tarifa reducida 0.5%</td><td>0.5</td></tr><tr><td>`10`</td><td>Tarifa exenta</td><td>0</td></tr><tr><td>`11`</td><td>Tarifa 0% sin derecho a crédito</td><td>0</td></tr></tbody></table>

Para el impuesto `08` se envía además `factor`. Para los impuestos `03`, `04`, `05` y `06` pueden enviarse los datos específicos `cantidadUnidadMedida`, `porcentaje`, `proporcion`, `volumenUnidadConsumo` e `impuestoUnidad`. La exoneración se declara dentro del impuesto `01` con los campos `exoneracionTipo`, `exoneracionNumero`, `exoneracionInstitucion`, `exoneracionFecha` en formato `dd/mm/aaaa` y `exoneracionTarifa`.

## Respuesta

Una emisión procesada devuelve **HTTP 200**. El campo `codigo` del cuerpo indica el resultado de la recepción en Hacienda y es independiente del código HTTP.

```json
{
  "codigo": 200,
  "contenidoXml": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iV…",
  "contenidoXmlFirmado": "Nfdsfffadeec2lvbj0iMS4wIiBlbmNvZGluZz0iV…",
  "documento": {
    "clave": "50622032000070175094601000001020000000007118491223",
    "consecutivo": "00400001020000000007",
    "recepcion": "recibido",
    "comprobacion": "por_comprobar"
  },
  "errores": []
}
```

La clave y el consecutivo devueltos corresponden a la **nota de débito recién emitida**, no al documento de referencia. El tipo de documento `02` en la posición correspondiente identifica la nota de débito.

<table id="bkmrk-campodescripci%C3%B3n-cod"><thead><tr><th>Campo</th><th>Descripción</th></tr></thead><tbody><tr><td>`codigo`</td><td>Resultado de la recepción en Hacienda. `200` si el documento fue recibido; `500` si no se pudo entregar.</td></tr><tr><td>`contenidoXml`</td><td>XML generado, codificado en `base64`.</td></tr><tr><td>`contenidoXmlFirmado`</td><td>XML firmado, codificado en `base64`. Es `null` cuando la firma o el envío no se completaron.</td></tr><tr><td>`documento.clave`</td><td>Clave numérica de 50 dígitos de la nota de débito.</td></tr><tr><td>`documento.consecutivo`</td><td>Consecutivo de 20 dígitos de la nota de débito.</td></tr><tr><td>`documento.recepcion`</td><td>Estado de la recepción: `recibido` o `por_enviar`.</td></tr><tr><td>`documento.comprobacion`</td><td>Estado de la comprobación: `por_comprobar`, `aceptado` o `rechazado`.</td></tr><tr><td>`errores`</td><td>Arreglo de objetos `{"tipo": "...", "mensaje": "..."}` devueltos por Hacienda.</td></tr></tbody></table>

## Errores

<table id="bkmrk-httpcuerpocausa-302r"><thead><tr><th>HTTP</th><th>Cuerpo</th><th>Causa</th></tr></thead><tbody><tr><td>302</td><td>Redirección al inicio de sesión</td><td>Falta el encabezado `Accept: application/json` en una petición no autenticada.</td></tr><tr><td>401</td><td>`{"message": "Unauthenticated."}`</td><td>`api-token` o `access-token` inválidos o ausentes.</td></tr><tr><td>403</td><td>`{"error": "No posee un Plan Api activo"}`</td><td>El plan de la cuenta no incluye acceso a API.</td></tr><tr><td>403</td><td>`{"error": "Ha llegado al límite de facturas del Plan Api contratado"}`</td><td>Se agotaron los documentos del ciclo vigente.</td></tr><tr><td>422</td><td>`{"errors": {"campo": ["mensaje"]}}`</td><td>Uno o más campos no cumplen las reglas de validación.</td></tr><tr><td>403</td><td>`{"error": "Factura no encontrada"}`</td><td>La clave del documento de referencia no existe o pertenece a otra cuenta.</td></tr><tr><td>500</td><td>`{"0": "Ha ocurrido un error", "error": "...", "stack": [...]}`</td><td>Error no controlado durante el procesamiento.</td></tr></tbody></table>

Los tres códigos `403` confirman que la autenticación fue correcta: el problema está en el plan o en la clave de referencia, no en las credenciales.

## Comprobación

La recepción es el primer paso: significa que Hacienda recibió el documento, no que lo aprobó. La comprobación se realiza automáticamente, por lo general en uno o dos minutos, y el estado pasa de `por_comprobar` a `aceptado` o `rechazado`.