# Emisión de documentos elecrónicos

Ejemplos de cómo emitir un documento electrónico:

- Factura electrónica
- Nota de crédito
- Nota de débito
- Tiquete electrónico

# Factura electrónica

<p class="callout info">**Endpoint**  
*POST* /api/2.0/documentos-electronicos/emision/factura</p>

Crea y envía a Hacienda una factura electrónica con la disposición 4.4. La emisión es síncrona: la respuesta incluye el XML generado, el XML firmado y el resultado de la recepción por parte de Hacienda.

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

## Ejemplo mínimo

Los siguientes datos son los mínimos para emitir una factura de contado.

```shell
curl --location 'https://app.facturadorvirtual.com/api/2.0/documentos-electronicos/emision/factura' \
--header 'api-token: iuJPbVCYQY3AmWuVHMflT9ZySlwzxb9ehviLbHNsz6yQnBm4' \
--header 'access-token: IDq4ME4ZUO9YmQ0fOc43AFp7mMO6talIuIALFaUUcs2H2pwLpYN2' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "actividad": "014002",
    "codigo_actividad_receptor": "851207",
    "condicion_venta": "01",
    "moneda": "CRC",
    "tipo_cambio": 1,
    "medio_pago": {
        "01": {
            "codigo": "01",
            "total": 1130
        }
    },
    "tipo_cedula": "01",
    "cedula": "701750946",
    "nombre": "Prueba",
    "correo": "prueba@prueba.com",
    "telefono": "88888888",
    "comentarios": "Factura de prueba por medio del API",
    "lineas": [
        {
            "codigo": "00001",
            "codigoCabys": "0196109000000",
            "descripcion": "Entrada a CRFW22",
            "cantidad": "1",
            "unidad": "Unid",
            "descuento": 0,
            "naturalezaDescuento": "",
            "precioUnitario": 1000,
            "impuestos": {
                "01": {
                    "tarifa": "08"
                }
            }
        }
    ]
}'
```

## 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>`condicion_venta`</td><td>string</td><td>Código de condición de venta. Ver la tabla más abajo.</td></tr><tr><td>`moneda`</td><td>string</td><td>Código de moneda, por ejemplo `CRC` o `USD`.</td></tr><tr><td>`medio_pago`</td><td>object</td><td>De 1 a 4 medios de pago. Ver la tabla más abajo. Se ignora cuando la condición de venta es a crédito.</td></tr><tr><td>`tipo_cedula`</td><td>string</td><td>Tipo de identificación del receptor. Valores aceptados: `01` física, `02` jurídica, `03` DIMEX, `04` NITE.</td></tr><tr><td>`cedula`</td><td>string</td><td>Identificación del receptor, máximo 20 caracteres. Los guiones se eliminan automáticamente.</td></tr><tr><td>`nombre`</td><td>string</td><td>Nombre del receptor, máximo 80 caracteres.</td></tr><tr><td>`correo`</td><td>string</td><td>Correo electrónico del receptor. Debe ser una dirección válida; a él se envía el comprobante.</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>`codigo_actividad_receptor`</td><td>string</td><td>Código de actividad económica del receptor. Hacienda lo exige para receptores nacionales, por lo que se recomienda enviarlo siempre.</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 de la cuenta.</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>`tipo_cambio`</td><td>number</td><td>Tipo de cambio, mayor que cero. Si se omite se asume `1`; cuando `moneda` es `USD` y no se envía, el sistema aplica automáticamente el tipo de cambio de referencia del día.</td></tr><tr><td>`telefono`</td><td>string</td><td>Teléfono del receptor. Se conservan únicamente los dígitos.</td></tr><tr><td>`nombre_comercial`</td><td>string</td><td>Nombre comercial del receptor, entre 3 y 80 caracteres.</td></tr><tr><td>`correo-copia`</td><td>string</td><td>Se acepta y se valida como dirección de correo, pero **actualmente no tiene efecto** en la emisión por API: no se registran destinatarios en copia. Para enviar copias, configure las preferencias de correo de la cuenta.</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. Ver la sección correspondiente.</td></tr><tr><td>`provincia`, `canton`, `distrito`, `barrio`, `direccion`</td><td>mixed</td><td>Ubicación del receptor. Solo se incorporan al XML si la preferencia de facturación «especificar dirección» está activa en la cuenta.</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>

## Condición de venta

<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>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-1"><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>

Por compatibilidad con la versión 4.3 también se acepta un arreglo simple de códigos, en cuyo caso el total del comprobante se asigna íntegro al primer medio: `"medio_pago": ["01"]`.

## 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`. La categoría del código determina si la línea se registra como mercancía o como servicio.</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. Permite vincular la línea con el producto registrado.</td></tr><tr><td>`id_producto`</td><td>integer</td><td>Identificador del producto en Facturador Virtual, como alternativa a `codigoInternoFV`.</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. 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».</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`.

### Exoneración

La exoneración se declara dentro del impuesto `01` de la línea.

```json
"impuestos": {
    "01": {
        "tarifa": "08",
        "exoneracionTipo": "02",
        "exoneracionNumero": "12345",
        "exoneracionInstitucion": "01",
        "exoneracionFecha": "15/01/2026",
        "exoneracionTarifa": 13,
        "exoneracionArticulo": 5,
        "exoneracionInciso": 2
    }
}
```

<table id="bkmrk-campodescripci%C3%B3n-exo"><thead><tr><th>Campo</th><th>Descripción</th></tr></thead><tbody><tr><td>`exoneracionTipo`</td><td>Tipo de documento de exoneración. Obligatorio para activar la exoneración.</td></tr><tr><td>`exoneracionNumero`</td><td>Número del documento de exoneración.</td></tr><tr><td>`exoneracionInstitucion`</td><td>Código de la institución que emite el documento.</td></tr><tr><td>`exoneracionFecha`</td><td>Fecha de emisión en formato `dd/mm/aaaa`.</td></tr><tr><td>`exoneracionTarifa`</td><td>Porcentaje de exoneración. Su presencia es la que activa el bloque de exoneración.</td></tr><tr><td>`exoneracionTipoOtro`</td><td>Obligatorio cuando `exoneracionTipo` es `99`.</td></tr><tr><td>`exoneracionArticulo`, `exoneracionInciso`</td><td>Obligatorios cuando `exoneracionTipo` es `02`, `03`, `06`, `07` u `08`.</td></tr><tr><td>`exoneracionInstitucionOtros`</td><td>Obligatorio cuando `exoneracionInstitucion` es `99`.</td></tr></tbody></table>

## Otros cargos

```json
"cargos": [
    {
        "tipo": "04",
        "detalle": "Comisión de servicio",
        "monto": 500,
        "tipoIdentidadTercero": "01",
        "numeroIdentidadTercero": "701750946",
        "nombreTercero": "Tercero S.A.",
        "porcentajeTercero": 10
    }
]
```

Los campos `tipo`, `detalle` y `monto` aplican a todos los cargos. Los cuatro campos de tercero solo se envían cuando `tipo` es `04`.

## Información de referencia y de proveedor

Para incorporar una referencia a otro documento se envía `incluir_info_referencia` junto con `tipo_documento`, `numero_referencia`, `codigo_referencia`, `fecha_emision` en formato `dd/mm/aaaa` y `razon_referencia`. Cuando el tipo o el código corresponden a «otros», se agregan `tipo_documento_otro` y `codigo_referencia_otro`.

Para incorporar los datos del proveedor se envía `incluir-info-proveedor` junto con `tipo-identificador`, `numero-identificador` y `orden-compra`.

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

<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 del comprobante.</td></tr><tr><td>`documento.consecutivo`</td><td>Consecutivo de 20 dígitos del comprobante.</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>

Cuando el documento se genera pero Hacienda no lo recibe, el comprobante queda registrado y el sistema reintenta el envío automáticamente:

```json
{
  "codigo": 500,
  "contenidoXml": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iV…",
  "contenidoXmlFirmado": null,
  "documento": {
    "clave": "50622032000070175094601000001010000000006118491223",
    "consecutivo": "00400001010000000006",
    "recepcion": "por_enviar",
    "comprobacion": "por_comprobar"
  },
  "errores": [
    {
      "tipo": "error",
      "mensaje": "No se ha podido enviar el documento a Hacienda porque su servicio de recepción presenta inconsistencias. El sistema intentará automáticamente en unos minutos"
    }
  ]
}
```

## 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. La clave de cada error es la ruta del campo, por ejemplo `lineas.0.descripcion`.</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>

<p class="callout warning">Existe además un caso en el que la respuesta es **HTTP 200** con `"codigo": 500`, `"documento": null` y `"errores": []`. Ocurre cuando el comprobante no llegó a construirse; la causa más frecuente es un código de `unidad` que no existe en el catálogo de unidades de medida. Verifique ese campo antes de reintentar.</p>

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

# Tiquete electrónico

<p class="callout info">**Endpoint**  
*POST* /api/2.0/documentos-electronicos/emision/tiquete</p>

Crea y envía a Hacienda un tiquete electrónico con la disposición 4.4. A diferencia de la factura electrónica, el tiquete no exige identificar al receptor: los datos del cliente son opcionales y se envían como un bloque completo cuando se desean incluir.

<p class="callout warning">El campo `tipo_documento` con valor `"04"` es **obligatorio** en este endpoint. Una petición que lo omita se rechaza con `422` antes de llegar a Hacienda.</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.

## Ejemplo mínimo

Los siguientes datos son los mínimos para emitir un tiquete de contado sin receptor identificado.

```shell
curl --location 'https://app.facturadorvirtual.com/api/2.0/documentos-electronicos/emision/tiquete' \
--header 'api-token: iuJPbVCYQY3AmWuVHMflT9ZySlwzxb9ehviLbHNsz6yQnBm4' \
--header 'access-token: IDq4ME4ZUO9YmQ0fOc43AFp7mMO6talIuIALFaUUcs2H2pwLpYN2' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "tipo_documento": "04",
    "actividad": "014002",
    "condicion_venta": "01",
    "moneda": "CRC",
    "tipo_cambio": 1,
    "medio_pago": {
        "01": {
            "codigo": "01",
            "total": 1130
        }
    },
    "comentarios": "Tiquete de prueba por medio del API",
    "lineas": [
        {
            "codigo": "00001",
            "codigoCabys": "0196109000000",
            "descripcion": "Entrada a CRFW22",
            "cantidad": "1",
            "unidad": "Unid",
            "descuento": 0,
            "naturalezaDescuento": "",
            "precioUnitario": 1000,
            "impuestos": {
                "01": {
                    "tarifa": "08"
                }
            }
        }
    ]
}'
```

## 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>`tipo_documento`</td><td>string</td><td>Debe ser exactamente `"04"`, el código de tiquete electrónico. Cualquier otro valor se rechaza.</td></tr><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>`condicion_venta`</td><td>string</td><td>Código de condición de venta. Ver la tabla más abajo.</td></tr><tr><td>`moneda`</td><td>string</td><td>Código de moneda, por ejemplo `CRC` o `USD`.</td></tr><tr><td>`medio_pago`</td><td>object</td><td>De 1 a 4 medios de pago. Ver la tabla más abajo. 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>`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>`tipo_cambio`</td><td>number</td><td>Tipo de cambio, mayor que cero. Si se omite se asume `1`; cuando `moneda` es `USD` y no se envía, el sistema aplica automáticamente el tipo de cambio de referencia del día.</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. Ver la sección correspondiente.</td></tr><tr><td>`correo-copia`</td><td>string</td><td>Se acepta y se valida como dirección de correo, pero **actualmente no tiene efecto** en la emisión por API: no se registran destinatarios en copia. Para enviar copias, configure las preferencias de correo de la cuenta.</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><tr><td>`cedula`, `nombre`, `correo`</td><td>Se envía `tipo_cedula`</td><td>Ver la sección «Receptor».</td></tr></tbody></table>

## Receptor

El receptor es opcional en el tiquete electrónico. Para incluirlo se envía el siguiente bloque:

```json
"tipo_cedula": "01",
"cedula": "701750946",
"nombre": "Prueba",
"correo": "prueba@prueba.com",
"telefono": "88888888",
"codigo_actividad_receptor": "851207"
```

<p class="callout warning">Los campos `cedula`, `nombre` y `correo` se vuelven **obligatorios en cuanto se envía `tipo_cedula`**. Si desea omitir el receptor, omita los cinco campos en conjunto; enviar el bloque a medias produce un error `422`.</p>

<table id="bkmrk-campodescripci%C3%B3n-tip"><thead><tr><th>Campo</th><th>Descripción</th></tr></thead><tbody><tr><td>`tipo_cedula`</td><td>Tipo de identificación. Valores aceptados: `01` física, `02` jurídica, `03` DIMEX, `04` NITE.</td></tr><tr><td>`cedula`</td><td>Identificación del receptor, máximo 20 caracteres. Los guiones se eliminan automáticamente.</td></tr><tr><td>`nombre`</td><td>Nombre del receptor, máximo 80 caracteres.</td></tr><tr><td>`correo`</td><td>Correo electrónico del receptor. Debe ser una dirección válida; a él se envía el comprobante.</td></tr><tr><td>`telefono`</td><td>Teléfono del receptor. Opcional. Se conservan únicamente los dígitos.</td></tr><tr><td>`codigo_actividad_receptor`</td><td>Código de actividad económica del receptor. Opcional.</td></tr><tr><td>`nombre_comercial`</td><td>Nombre comercial del receptor. Opcional; si se envía, entre 3 y 80 caracteres.</td></tr></tbody></table>

## Condición de venta

<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>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.</p>

## Medios de pago

`medio_pago` es un objeto 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 }
}
```

Se admiten entre uno y cuatro medios de pago.

<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>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>

Por compatibilidad con la versión 4.3 también se acepta un arreglo simple de códigos, en cuyo caso el total del comprobante se asigna íntegro al primer medio: `"medio_pago": ["01"]`.

## 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`. La categoría del código determina si la línea se registra como mercancía o como servicio.</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. Permite vincular la línea con el producto registrado.</td></tr><tr><td>`id_producto`</td><td>integer</td><td>Identificador del producto en Facturador Virtual, como alternativa a `codigoInternoFV`.</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. 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».</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`.

### Exoneración

La exoneración se declara dentro del impuesto `01` de la línea.

```json
"impuestos": {
    "01": {
        "tarifa": "08",
        "exoneracionTipo": "02",
        "exoneracionNumero": "12345",
        "exoneracionInstitucion": "01",
        "exoneracionFecha": "15/01/2026",
        "exoneracionTarifa": 13,
        "exoneracionArticulo": 5,
        "exoneracionInciso": 2
    }
}
```

<table id="bkmrk-campodescripci%C3%B3n-exo"><thead><tr><th>Campo</th><th>Descripción</th></tr></thead><tbody><tr><td>`exoneracionTipo`</td><td>Tipo de documento de exoneración.</td></tr><tr><td>`exoneracionNumero`</td><td>Número del documento de exoneración.</td></tr><tr><td>`exoneracionInstitucion`</td><td>Código de la institución que emite el documento.</td></tr><tr><td>`exoneracionFecha`</td><td>Fecha de emisión en formato `dd/mm/aaaa`.</td></tr><tr><td>`exoneracionTarifa`</td><td>Porcentaje de exoneración. Su presencia es la que activa el bloque de exoneración.</td></tr><tr><td>`exoneracionTipoOtro`</td><td>Obligatorio cuando `exoneracionTipo` es `99`.</td></tr><tr><td>`exoneracionArticulo`, `exoneracionInciso`</td><td>Obligatorios cuando `exoneracionTipo` es `02`, `03`, `06`, `07` u `08`.</td></tr><tr><td>`exoneracionInstitucionOtros`</td><td>Obligatorio cuando `exoneracionInstitucion` es `99`.</td></tr></tbody></table>

## Otros cargos

```json
"cargos": [
    {
        "tipo": "04",
        "detalle": "Comisión de servicio",
        "monto": 500,
        "tipoIdentidadTercero": "01",
        "numeroIdentidadTercero": "701750946",
        "nombreTercero": "Tercero S.A.",
        "porcentajeTercero": 10
    }
]
```

Los campos `tipo`, `detalle` y `monto` aplican a todos los cargos. Los cuatro campos de tercero solo se envían cuando `tipo` es `04`.

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

<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 del comprobante.</td></tr><tr><td>`documento.consecutivo`</td><td>Consecutivo de 20 dígitos del comprobante.</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>

Cuando el documento se genera pero Hacienda no lo recibe, el comprobante queda registrado y el sistema reintenta el envío automáticamente:

```json
{
  "codigo": 500,
  "contenidoXml": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iV…",
  "contenidoXmlFirmado": null,
  "documento": {
    "clave": "50622032000070175094601000001040000000006118491223",
    "consecutivo": "00400001040000000006",
    "recepcion": "por_enviar",
    "comprobacion": "por_comprobar"
  },
  "errores": [
    {
      "tipo": "error",
      "mensaje": "No se ha podido enviar el documento a Hacienda porque su servicio de recepción presenta inconsistencias. El sistema intentará automáticamente en unos minutos"
    }
  ]
}
```

## 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. Las causas más frecuentes son omitir `tipo_documento` y enviar `tipo_cedula` sin el resto del bloque del receptor.</td></tr><tr><td>500</td><td>`{"error": "...", "pila": [...]}`</td><td>Error no controlado durante el procesamiento.</td></tr></tbody></table>

<p class="callout warning">Existe además un caso en el que la respuesta es **HTTP 200** con `"codigo": 500`, `"documento": null` y `"errores": []`. Ocurre cuando el comprobante no llegó a construirse; la causa más frecuente es un código de `unidad` que no existe en el catálogo de unidades de medida. Verifique ese campo antes de reintentar.</p>

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

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

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

# Factura electrónica de exportación

<p class="callout info">**Endpoint**  
*POST* /api/2.0/documentos-electronicos/emision/exportacion</p>

Crea y envía a Hacienda una factura electrónica de exportación con la disposición 4.4. Es el comprobante para ventas a receptores en el extranjero, y se distingue de la factura ordinaria en tres puntos: el receptor es opcional y se identifica como extranjero, cada línea de mercancía puede declarar su partida arancelaria, y normalmente se emite en moneda extranjera.

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

## Ejemplo mínimo

```shell
curl --location 'https://app.facturadorvirtual.com/api/2.0/documentos-electronicos/emision/exportacion' \
--header 'api-token: iuJPbVCYQY3AmWuVHMflT9ZySlwzxb9ehviLbHNsz6yQnBm4' \
--header 'access-token: IDq4ME4ZUO9YmQ0fOc43AFp7mMO6talIuIALFaUUcs2H2pwLpYN2' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "actividad": "014002",
    "condicion_venta": "01",
    "moneda": "USD",
    "tipo_cambio": 512.45,
    "medio_pago": {
        "04": {
            "codigo": "04",
            "total": 1000
        }
    },
    "incliuir_receptor": 1,
    "tipo_cedula": "05",
    "cedula": "US-8891234",
    "nombre": "Costa Rica Coffee Imports LLC",
    "correo": "purchasing@crcoffee.example",
    "comentarios": "Exportación de prueba por medio del API",
    "lineas": [
        {
            "codigo": "00001",
            "codigoCabys": "0161010100000",
            "descripcion": "Café oro en sacos de 69 kg",
            "cantidad": "10",
            "unidad": "Kg",
            "partidaArancelaria": "090111000000",
            "descuento": 0,
            "naturalezaDescuento": "",
            "precioUnitario": 100,
            "impuestos": {
                "01": {
                    "tarifa": "01"
                }
            }
        }
    ]
}'
```

## 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>`condicion_venta`</td><td>string</td><td>Código de condición de venta. Ver la tabla más abajo.</td></tr><tr><td>`moneda`</td><td>string</td><td>Código de moneda. En una exportación es habitual `USD` o `EUR`.</td></tr><tr><td>`medio_pago`</td><td>object</td><td>De 1 a 4 medios de pago. Ver la tabla más abajo. 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>`tipo_cambio`</td><td>number</td><td>Tipo de cambio respecto al colón, mayor que cero. Si se omite se asume `1`; cuando `moneda` es `USD` y no se envía, el sistema aplica automáticamente el tipo de cambio de referencia del día. Para otras monedas debe enviarse explícitamente.</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>`nombre_comercial`</td><td>string</td><td>Nombre comercial del receptor, entre 3 y 80 caracteres.</td></tr><tr><td>`codigo_actividad_receptor`</td><td>string</td><td>Código de actividad económica del receptor.</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. Ver la sección correspondiente.</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><tr><td>`cedula`, `nombre`, `correo`</td><td>Se envía `incliuir_receptor`</td><td>Ver la sección «Receptor».</td></tr></tbody></table>

## Receptor

En la factura de exportación el receptor es opcional. Para incluirlo se envía el indicador `incliuir_receptor` junto con los datos del cliente:

```json
"incliuir_receptor": 1,
"tipo_cedula": "05",
"cedula": "US-8891234",
"nombre": "Costa Rica Coffee Imports LLC",
"correo": "purchasing@crcoffee.example",
"telefono": "18005550123",
"nombre_comercial": "CR Coffee"
```

<p class="callout warning">El indicador se llama `incliuir_receptor`, con esa grafía exacta. Es el nombre del campo tal como lo espera el sistema en todas sus interfaces; escrito de otra forma, el indicador no se reconoce y los datos del receptor dejan de ser obligatorios.</p>

Al enviar `incliuir_receptor`, los campos `cedula`, `nombre` y `correo` pasan a ser obligatorios. Si se omite el indicador, esos campos siguen aceptándose y se incorporan al comprobante, pero no se exige ninguno; omitiéndolos todos, el documento se emite sin receptor identificado.

<table id="bkmrk-campodescripci%C3%B3n-inc"><thead><tr><th>Campo</th><th>Descripción</th></tr></thead><tbody><tr><td>`incliuir_receptor`</td><td>Indicador de inclusión del receptor. Envíe `1`.</td></tr><tr><td>`tipo_cedula`</td><td>Tipo de identificación. Para un receptor en el extranjero corresponde `05`, extranjero no domiciliado. El valor `99` se acepta y se normaliza a `05`.</td></tr><tr><td>`cedula`</td><td>Identificación del receptor, máximo 20 caracteres. En receptores extranjeros se conserva tal cual, sin eliminar guiones.</td></tr><tr><td>`nombre`</td><td>Nombre del receptor, máximo 80 caracteres.</td></tr><tr><td>`correo`</td><td>Correo electrónico del receptor. Debe ser una dirección válida; a él se envía el comprobante.</td></tr><tr><td>`telefono`</td><td>Teléfono del receptor. Opcional. Se conservan únicamente los dígitos.</td></tr><tr><td>`nombre_comercial`</td><td>Nombre comercial del receptor, entre 3 y 80 caracteres.</td></tr></tbody></table>

## Condición de venta

<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>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": {
    "04": { "codigo": "04", "total": 1000 }
}
```

<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>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`, `Kg`, `L`, `Sp`, `Os`. La categoría del código determina si la línea se registra como mercancía o como servicio.</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>`partidaArancelaria`</td><td>string</td><td>Partida arancelaria de la mercancía. Si se envía, debe tener **exactamente 12 caracteres**. Es el campo propio de la factura de exportación.</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>`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. En una exportación lo habitual es aplicar una tarifa de 0 %.

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

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

## Otros cargos

```json
"cargos": [
    {
        "tipo": "04",
        "detalle": "Flete internacional",
        "monto": 150,
        "tipoIdentidadTercero": "01",
        "numeroIdentidadTercero": "701750946",
        "nombreTercero": "Naviera S.A.",
        "porcentajeTercero": 10
    }
]
```

Los campos `tipo`, `detalle` y `monto` aplican a todos los cargos. Los cuatro campos de tercero solo se envían cuando `tipo` es `04`.

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

El tipo de documento `09` dentro del consecutivo identifica la factura de exportación.

<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 del comprobante.</td></tr><tr><td>`documento.consecutivo`</td><td>Consecutivo de 20 dígitos del comprobante.</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. Una causa frecuente es una `partidaArancelaria` que no tiene exactamente 12 caracteres.</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>

<p class="callout warning">Existe además un caso en el que la respuesta es **HTTP 200** con `"codigo": 500`, `"documento": null` y `"errores": []`. Ocurre cuando el comprobante no llegó a construirse; la causa más frecuente es un código de `unidad` que no existe en el catálogo de unidades de medida. Verifique ese campo antes de reintentar.</p>

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

# Factura electrónica de compra

<p class="callout info">**Endpoint**  
*POST* /api/2.0/documentos-electronicos/emision/compra</p>

Crea y envía a Hacienda una factura electrónica de compra con la disposición 4.4. Es el comprobante que el **comprador se autoemite** cuando adquiere bienes o servicios de alguien que no puede emitir un comprobante electrónico —por ejemplo, un productor agrícola no inscrito—, de modo que la compra quede respaldada como gasto deducible.

<p class="callout danger">En este documento **los papeles están invertidos respecto de los demás comprobantes**. Los campos `cedula`, `tipo_cedula`, `nombre`, `nombre_comercial` y `correo` que se envían en el cuerpo describen al **vendedor**, que figura como emisor del XML. El receptor es siempre la cuenta que hace la petición, y sus datos se toman del perfil, no del cuerpo.</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.

## Ejemplo mínimo

El siguiente ejemplo documenta la compra de 100 kg de papaya a un productor no inscrito.

```shell
curl --location 'https://app.facturadorvirtual.com/api/2.0/documentos-electronicos/emision/compra' \
--header 'api-token: iuJPbVCYQY3AmWuVHMflT9ZySlwzxb9ehviLbHNsz6yQnBm4' \
--header 'access-token: IDq4ME4ZUO9YmQ0fOc43AFp7mMO6talIuIALFaUUcs2H2pwLpYN2' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "actividad": "014002",
    "codigo_actividad_receptor": "014002",
    "condicion_venta": "01",
    "moneda": "CRC",
    "tipo_cambio": 1,
    "medio_pago": {
        "01": {
            "codigo": "01",
            "total": 50000
        }
    },
    "tipo_cedula": "01",
    "cedula": "601230456",
    "nombre": "Juan Rodríguez Mora",
    "correo": "jrodriguez@example.com",
    "tipo_documento": "99",
    "tipo_documento_otro": "Compra a productor no inscrito",
    "numero_referencia": "PAPAYA-2026-0001",
    "codigo_referencia": "04",
    "fecha_emision": "15/01/2026",
    "razon_referencia": "Compra de producto agrícola a productor no inscrito",
    "comentarios": "Compra de papaya a productor local",
    "lineas": [
        {
            "codigo": "PAPAYA",
            "codigoCabys": "0113101000000",
            "descripcion": "Papaya fresca",
            "cantidad": "100",
            "unidad": "Kg",
            "descuento": 0,
            "naturalezaDescuento": "",
            "precioUnitario": 500,
            "impuestos": {
                "01": {
                    "tarifa": "01"
                }
            }
        }
    ]
}'
```

## El vendedor

Los datos del vendedor son **obligatorios**: son los que identifican al emisor del comprobante.

```json
"tipo_cedula": "01",
"cedula": "601230456",
"nombre": "Juan Rodríguez Mora",
"correo": "jrodriguez@example.com",
"nombre_comercial": "Finca La Esperanza"
```

<table id="bkmrk-campodescripci%C3%B3n-tip"><thead><tr><th>Campo</th><th>Descripción</th></tr></thead><tbody><tr><td>`tipo_cedula`</td><td>Tipo de identificación del vendedor. Valores aceptados: `01` física, `02` jurídica, `03` DIMEX, `04` NITE, `05` extranjero no domiciliado, `06` no contribuyente.</td></tr><tr><td>`cedula`</td><td>Identificación del vendedor, máximo 20 caracteres. Los guiones se eliminan automáticamente.</td></tr><tr><td>`nombre`</td><td>Nombre del vendedor, máximo 80 caracteres.</td></tr><tr><td>`correo`</td><td>Correo electrónico del vendedor. Debe ser una dirección válida.</td></tr><tr><td>`nombre_comercial`</td><td>Nombre comercial del vendedor, entre 3 y 80 caracteres.</td></tr><tr><td>`otras_sennas_extranjero`</td><td>Dirección del vendedor. **Obligatoria cuando `tipo_cedula` es `05`**, entre 5 y 300 caracteres; en los demás casos se ignora. Nótese la grafía del campo.</td></tr></tbody></table>

## Información de referencia

<p class="callout warning">A diferencia del resto de comprobantes, en la factura de compra el bloque de información de referencia **siempre se construye** y no depende de ningún indicador. Por eso sus cinco primeros campos son obligatorios.</p>

<table id="bkmrk-campodescripci%C3%B3n-tip-1"><thead><tr><th>Campo</th><th>Descripción</th></tr></thead><tbody><tr><td>`tipo_documento`</td><td>Obligatorio. Tipo del documento de referencia. Ver la tabla de tipos.</td></tr><tr><td>`numero_referencia`</td><td>Obligatorio. Número o identificador del documento de referencia, máximo 50 caracteres.</td></tr><tr><td>`codigo_referencia`</td><td>Obligatorio. Código que indica el motivo de la referencia. Ver la tabla de códigos.</td></tr><tr><td>`fecha_emision`</td><td>Obligatoria. Fecha del documento de referencia, en formato `dd/mm/aaaa`.</td></tr><tr><td>`razon_referencia`</td><td>Obligatoria. Descripción del motivo de la referencia, máximo 100 caracteres.</td></tr><tr><td>`tipo_documento_otro`</td><td>Obligatorio cuando `tipo_documento` es `99`. Entre 5 y 100 caracteres.</td></tr><tr><td>`codigo_referencia_otro`</td><td>Obligatorio cuando `codigo_referencia` es `99`. Entre 5 y 100 caracteres.</td></tr></tbody></table>

### Tipos de documento de referencia

<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>Factura electrónica</td></tr><tr><td>`02`</td><td>Nota de débito electrónica</td></tr><tr><td>`03`</td><td>Nota de crédito electrónica</td></tr><tr><td>`04`</td><td>Tiquete electrónico</td></tr><tr><td>`05`</td><td>Nota de despacho</td></tr><tr><td>`06`</td><td>Contrato</td></tr><tr><td>`07`</td><td>Procedimiento</td></tr><tr><td>`08`</td><td>Comprobante emitido en contingencia</td></tr><tr><td>`09`</td><td>Devolución de mercadería</td></tr><tr><td>`10`</td><td>Sustituye factura rechazada por el Ministerio de Hacienda</td></tr><tr><td>`11`</td><td>Sustituye factura rechazada por el receptor del comprobante</td></tr><tr><td>`12`</td><td>Sustituye factura de exportación</td></tr><tr><td>`13`</td><td>Factura mes vencido</td></tr><tr><td>`14`</td><td>Comprobante aportado por contribuyente del Régimen de Tributación Simplificado</td></tr><tr><td>`15`</td><td>Sustituye una factura electrónica de compra</td></tr><tr><td>`16`</td><td>Comprobante de proveedor no domiciliado</td></tr><tr><td>`17`</td><td>Nota de crédito a factura electrónica de compra</td></tr><tr><td>`18`</td><td>Nota de débito a factura electrónica de compra</td></tr><tr><td>`99`</td><td>Otros. Requiere `tipo_documento_otro`.</td></tr></tbody></table>

### Códigos de referencia

<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>Anula documento de referencia</td></tr><tr><td>`02`</td><td>Corrige texto de documento de referencia</td></tr><tr><td>`03`</td><td>Corrige monto</td></tr><tr><td>`04`</td><td>Referencia a otro documento</td></tr><tr><td>`05`</td><td>Sustituye comprobante provisional por contingencia</td></tr><tr><td>`99`</td><td>Otros. Requiere `codigo_referencia_otro`.</td></tr></tbody></table>

## 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 registrada en la cuenta. Cuando se envía, también tiene precedencia sobre `codigo_actividad_receptor` como actividad registrada para el receptor.</td></tr><tr><td>`codigo_actividad_receptor`</td><td>string</td><td>Código de actividad económica del receptor.</td></tr><tr><td>`moneda`</td><td>string</td><td>Código de moneda, por ejemplo `CRC`.</td></tr><tr><td>`condicion_venta`</td><td>string</td><td>Código de condición de venta. 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><tr><td>`tipo_cedula`, `cedula`, `nombre`, `correo`</td><td>string</td><td>Datos del vendedor. Ver la sección «El vendedor».</td></tr><tr><td>`tipo_documento`, `numero_referencia`, `codigo_referencia`, `fecha_emision`, `razon_referencia`</td><td>string</td><td>Información de referencia. 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>`tipo_cambio`</td><td>number</td><td>Tipo de cambio, mayor que cero. Si se omite se asume `1`.</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.</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><tr><td>`otras_sennas_extranjero`</td><td>`tipo_cedula` es `05`</td><td>Texto entre 5 y 300 caracteres.</td></tr><tr><td>`tipo_documento_otro`</td><td>`tipo_documento` es `99`</td><td>Texto entre 5 y 100 caracteres.</td></tr><tr><td>`codigo_referencia_otro`</td><td>`codigo_referencia` es `99`</td><td>Texto entre 5 y 100 caracteres.</td></tr></tbody></table>

### Campos que este endpoint no aplica

<table id="bkmrk-campocomportamiento-"><thead><tr><th>Campo</th><th>Comportamiento</th></tr></thead><tbody><tr><td>`devolucion`</td><td>Se valida como número mayor que cero, pero **no se aplica**: la devolución de IVA del resumen queda siempre en cero.</td></tr><tr><td>`cargos`</td><td>No se procesa. La factura de compra no admite otros cargos.</td></tr><tr><td>`orden`</td><td>No se procesa. Tampoco se extrae un número de orden desde `comentarios`, como sí ocurre en la factura.</td></tr><tr><td>`correo-copia`</td><td>No se acepta ni se procesa.</td></tr><tr><td>`provincia`, `canton`, `distrito`, `barrio`, `direccion`</td><td>No se procesan. Para un vendedor extranjero use `otras_sennas_extranjero`.</td></tr></tbody></table>

## Condición de venta

<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>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.</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": 50000 }
}
```

<table id="bkmrk-c%C3%B3digodescripci%C3%B3n-01-3"><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 con un código del catálogo, por ejemplo `Unid`, `Kg`, `L`, `Sp`, `Os`.</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>`partidaArancelaria`</td><td>string</td><td>Partida arancelaria. Si se envía, debe tener exactamente 12 caracteres.</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>`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`.</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` y `formaFarmaceutica`.</td></tr><tr><td>`es_combo`</td><td>boolean</td><td>Marca la línea como combo. Los componentes se envían en `componentes`.</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.

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

<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>

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

El tipo de documento `08` dentro del consecutivo identifica la factura electrónica de compra.

<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 del comprobante.</td></tr><tr><td>`documento.consecutivo`</td><td>Consecutivo de 20 dígitos del comprobante.</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>500</td><td>`{"0": "Ha ocurrido un error", "error": "...", "stack": [...]}`</td><td>Error no controlado durante el procesamiento.</td></tr></tbody></table>

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