# Nota de crédito electrónica

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

Emite una nota de crédito electrónica con la disposición 4.4 sobre un documento ya emitido. A diferencia de la factura y el tiquete, 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 crédito **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 que se desea corregir o anular. 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-credito/50622032000070175094601000001010000000006118491223
```

## Ejemplo mínimo

```shell
curl --location --request PUT 'https://app.facturadorvirtual.com/api/2.0/documentos-electronicos/emision/nota-credito/50622032000070175094601000001010000000006118491223' \
--header 'api-token: iuJPbVCYQY3AmWuVHMflT9ZySlwzxb9ehviLbHNsz6yQnBm4' \
--header 'access-token: IDq4ME4ZUO9YmQ0fOc43AFp7mMO6talIuIALFaUUcs2H2pwLpYN2' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "actividad": "014002",
    "razon": "01",
    "condicion_venta": "01",
    "medio_pago": {
        "01": {
            "codigo": "01",
            "total": 1130
        }
    },
    "comentarios": "Anulación de la factura de referencia",
    "lineas": [
        {
            "codigo": "00001",
            "codigoCabys": "0196109000000",
            "descripcion": "Entrada a CRFW22",
            "cantidad": "1",
            "unidad": "Unid",
            "descuento": 0,
            "naturalezaDescuento": "",
            "precioUnitario": 1000,
            "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 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>Exclusivo de la nota de crédito. 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>

<p class="callout warning">Para anular por completo una factura sin reconstruir el detalle, conviene usar el endpoint de anulación descrito al final de esta página, que arma la nota a partir del documento original.</p>

## 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": "50622032000070175094601000001030000000007118491223",
    "consecutivo": "00400001030000000007",
    "recepcion": "recibido",
    "comprobacion": "por_comprobar"
  },
  "errores": []
}
```

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

<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 crédito.</td></tr><tr><td>`documento.consecutivo`</td><td>Consecutivo de 20 dígitos de la nota de crédito.</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.

## Anulación completa de un documento

Cuando el objetivo es anular por completo una factura, existe un endpoint que construye la nota de crédito a partir del documento original —líneas, impuestos, medios de pago y resumen— sin necesidad de reenviar el detalle.

<p class="callout info">**Endpoint**  
*POST* /api/2.0/documentos-electronicos/anular/factura/{clave}</p>

```shell
curl --location --request POST 'https://app.facturadorvirtual.com/api/2.0/documentos-electronicos/anular/factura/50622032000070175094601000001010000000006118491223' \
--header 'api-token: iuJPbVCYQY3AmWuVHMflT9ZySlwzxb9ehviLbHNsz6yQnBm4' \
--header 'access-token: IDq4ME4ZUO9YmQ0fOc43AFp7mMO6talIuIALFaUUcs2H2pwLpYN2' \
--header 'Accept: application/json'
```

La petición **no lleva cuerpo**. La respuesta tiene el mismo formato que la de la nota de crédito y corresponde a la nota generada. Si la clave no existe o pertenece a otra cuenta, responde `403` con `{"error": "Factura no encontrada"}`; si la anulación no puede completarse, responde `500` con el mensaje `No fue posible anular la factura`.

## 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`.