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