Factura electrónica de compra

Endpoint
POST /api/2.0/documentos-electronicos/emision/compra

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.

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.

Autenticación

Todas las peticiones requieren los cuatro encabezados siguientes.

Encabezado	Descripción
api-token	Token de API de la cuenta.
access-token	Token de acceso asociado al api-token.
Content-Type	application/json
Accept	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.

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.

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
        }
    },
    "incliuir_receptor": 1,
    "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 se envían activando el indicador incliuir_receptor:

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

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 vendedor dejan de ser obligatorios. Pese al nombre, en este documento gobierna los datos del emisor del XML, que es el vendedor.

Campo	Descripción
incliuir_receptor	Indicador de inclusión de los datos del vendedor. Envíe 1.
tipo_cedula	Tipo de identificación del vendedor: 01 física, 02 jurídica, 03 DIMEX, 04 NITE, 05 extranjero no domiciliado. No se valida contra el catálogo.
cedula	Identificación del vendedor, máximo 20 caracteres. Los guiones se eliminan automáticamente.
nombre	Nombre del vendedor, máximo 80 caracteres.
correo	Correo electrónico del vendedor. Debe ser una dirección válida.
nombre_comercial	Nombre comercial del vendedor, entre 3 y 80 caracteres.
otras_sennas_extranjero	Dirección del vendedor. Solo se incorpora cuando tipo_cedula es 05. Nótese la grafía del campo.

Información de referencia

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. Los cinco campos siguientes son obligatorios en la práctica: si falta cualquiera de ellos, la petición responde 500 antes de llegar a Hacienda. No están cubiertos por la validación, así que el error no llega como 422.

Campo	Descripción
tipo_documento	Tipo del documento de referencia. Ver la tabla de tipos.
numero_referencia	Número o identificador del documento de referencia.
codigo_referencia	Código que indica el motivo de la referencia. Ver la tabla de códigos.
fecha_emision	Fecha del documento de referencia, en formato dd/mm/aaaa.
razon_referencia	Descripción del motivo de la referencia.
tipo_documento_otro	Descripción cuando tipo_documento es 99.
codigo_referencia_otro	Descripción cuando codigo_referencia es 99.

Tipos de documento de referencia

Código	Descripción
01	Factura electrónica
02	Nota de débito electrónica
03	Nota de crédito electrónica
04	Tiquete electrónico
05	Nota de despacho
06	Contrato
07	Procedimiento
08	Comprobante emitido en contingencia
09	Devolución de mercadería
10	Sustituye factura rechazada por el Ministerio de Hacienda
11	Sustituye factura rechazada por el receptor del comprobante
12	Sustituye factura de exportación
13	Factura mes vencido
14	Comprobante aportado por contribuyente del Régimen de Tributación Simplificado
15	Sustituye una factura electrónica de compra
16	Comprobante de proveedor no domiciliado
17	Nota de crédito a factura electrónica de compra
18	Nota de débito a factura electrónica de compra
99	Otros. Requiere tipo_documento_otro.

Códigos de referencia

Código	Descripción
01	Anula documento de referencia
02	Corrige texto de documento de referencia
03	Corrige monto
04	Referencia a otro documento
05	Sustituye comprobante provisional por contingencia
99	Otros. Requiere codigo_referencia_otro.

Campos del documento

Obligatorios

Campo	Tipo	Descripción
codigo_actividad_receptor	string	Código de actividad económica. Es el único campo de actividad exigido por la validación.
actividad	string	Código de la actividad económica registrada en la cuenta. Obligatorio en la práctica: si se omite la petición responde 500. Cuando se envía, también tiene precedencia sobre codigo_actividad_receptor como actividad registrada para el receptor.
moneda	string	Código de moneda, por ejemplo CRC. Obligatorio en la práctica: si se omite la petición responde 500.
condicion_venta	string	Código de condición de venta. Ver la tabla más abajo.
medio_pago	object	De 1 a 4 medios de pago. Se ignora cuando la condición de venta es a crédito.
lineas	array	Al menos una línea de detalle. Ver la sección correspondiente.

Opcionales

Campo	Tipo	Descripción
tipo_cambio	number	Tipo de cambio, mayor que cero. Si se omite se asume 1.
sucursal	string	Código de sucursal, por ejemplo 004. Si se omite, se usa el valor configurado en las preferencias de facturación.
punto	string	Punto de emisión, por ejemplo 00001. Si se omite, se usa el valor configurado en las preferencias de facturación.
comentarios	string	Notas del comprobante.

Campos condicionales

Campo	Se vuelve obligatorio cuando…	Reglas
plazo_credito	condicion_venta es 02 o 10	Entero entre 1 y 99999, expresado en días.
condicion_venta_otros	condicion_venta es 99	Texto entre 5 y 100 caracteres.
medio_pago.<codigo>.detalle	El código del medio de pago es 99	Texto entre 3 y 100 caracteres.
cedula, nombre, correo	Se envía incliuir_receptor	Ver la sección «El vendedor».

Campos que este endpoint no aplica

Campo	Comportamiento
devolucion	Se valida como número mayor que cero, pero no se aplica: la devolución de IVA del resumen queda siempre en cero.
cargos	No se procesa. La factura de compra no admite otros cargos.
orden	No se procesa. Tampoco se extrae un número de orden desde comentarios, como sí ocurre en la factura.
correo-copia	No se acepta ni se procesa.
provincia, canton, distrito, barrio, direccion	No se procesan. Para un vendedor extranjero use otras_sennas_extranjero.

Condición de venta

Código	Descripción
01	Contado
02	Crédito
03	Consignación
04	Apartado
05	Arrendamiento con opción de compra
06	Arrendamiento en función financiera
07	Cobro a favor de un tercero
08	Servicios prestados al Estado
09	Pago de servicios prestados al Estado
10	Venta a crédito en IVA hasta 90 días
11	Pago de venta a crédito en IVA hasta 90 días
12	Venta de mercancía no nacionalizada
13	Venta de bienes usados no contribuyente
14	Arrendamiento operativo
15	Arrendamiento financiero
99	Otros. Requiere condicion_venta_otros.

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.

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.

"medio_pago": {
    "01": { "codigo": "01", "total": 50000 }
}

Código	Descripción
01	Efectivo
02	Tarjeta
03	Cheque
04	Transferencia o depósito bancario
05	Recaudado por terceros
06	SINPE Móvil
07	Plataforma digital
99	Otros. Requiere detalle.

Líneas de detalle

Campos obligatorios de la línea

Campo	Tipo	Descripción
codigo	string	Código del producto o servicio, máximo 20 caracteres.
descripcion	string	Detalle de la línea, entre 3 y 200 caracteres.
cantidad	number	Cantidad, mayor que cero. Se redondea a 3 decimales.
unidad	string	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.
precioUnitario	number	Precio unitario, mayor o igual a cero.
descuento	number	Monto del descuento. Envíe 0 si no aplica.
naturalezaDescuento	string	Naturaleza del descuento. Envíe cadena vacía si no aplica; si se envía texto, debe tener entre 3 y 80 caracteres.

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.

Campos opcionales de la línea

Campo	Tipo	Descripción
codigoCabys	string	Código CABYS de 13 dígitos.
partidaArancelaria	string	Partida arancelaria. Si se envía, debe tener exactamente 12 caracteres.
codigoInternoFV	string	Código del producto en el catálogo de Facturador Virtual.
id_producto	integer	Identificador del producto en Facturador Virtual.
unidadMedidaComercial	string	Unidad de medida comercial, máximo 20 caracteres.
tipoTransaccion	string	Código de tipo de transacción de la versión 4.4.
tipoDescuento	string	Código del tipo de descuento, máximo 2 caracteres. Si se omite se asume 08.
tipoDescuentoOtro	string	Descripción cuando tipoDescuento corresponde a «otros». Entre 5 y 100 caracteres.
ivaCobradoFabrica	number	IVA cobrado en fábrica.
vinSerie	string	Número VIN o serie, para vehículos.
esCabysMedicamento	boolean	Marca la línea como medicamento. Al activarse se toman registroMedicamento y formaFarmaceutica.
es_combo	boolean	Marca la línea como combo. Los componentes se envían en componentes.
impuestos	object	Impuestos aplicados a la línea. Ver la siguiente sección.

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.

"impuestos": {
    "01": {
        "tarifa": "01"
    }
}

Código de impuesto	Descripción
01	Impuesto al Valor Agregado
02	Impuesto Selectivo de Consumo
03	Impuesto Único a los Combustibles
04	Impuesto específico de Bebidas Alcohólicas
05	Impuesto Específico sobre las bebidas envasadas sin contenido alcohólico y jabones de tocador
06	Impuesto a los Productos de Tabaco
07	IVA (cálculo especial)
08	IVA Régimen de Bienes Usados (Factor)
12	Impuesto Específico al Cemento
99	Otros. Se describe en descripcionOtro.

Código de tarifa	Descripción	Porcentaje aplicado
01	Tarifa 0% (Artículo 32, num 1, RLIVA)	0
02	Tarifa reducida 1%	1
03	Tarifa reducida 2%	2
04	Tarifa reducida 4%	4
05	Transitorio 0%	0
06	Transitorio 4%	4
07	Tarifa transitoria 8%	8
08	Tarifa general 13%	13
09	Tarifa reducida 0.5%	0.5
10	Tarifa exenta	0
11	Tarifa 0% sin derecho a crédito	0

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.

{
  "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.

Campo	Descripción
codigo	Resultado de la recepción en Hacienda. 200 si el documento fue recibido; 500 si no se pudo entregar.
contenidoXml	XML generado, codificado en base64.
contenidoXmlFirmado	XML firmado, codificado en base64. Es null cuando la firma o el envío no se completaron.
documento.clave	Clave numérica de 50 dígitos del comprobante.
documento.consecutivo	Consecutivo de 20 dígitos del comprobante.
documento.recepcion	Estado de la recepción: recibido o por_enviar.
documento.comprobacion	Estado de la comprobación: por_comprobar, aceptado o rechazado.
errores	Arreglo de objetos {"tipo": "...", "mensaje": "..."} devueltos por Hacienda.

Errores

HTTP	Cuerpo	Causa
302	Redirección al inicio de sesión	Falta el encabezado Accept: application/json en una petición no autenticada.
401	{"message": "Unauthenticated."}	api-token o access-token inválidos o ausentes.
403	{"error": "No posee un Plan Api activo"}	El plan de la cuenta no incluye acceso a API.
403	{"error": "Ha llegado al límite de facturas del Plan Api contratado"}	Se agotaron los documentos del ciclo vigente.
422	{"errors": {"campo": ["mensaje"]}}	Uno o más campos no cumplen las reglas de validación.
500	{"0": "Ha ocurrido un error", "error": "...", "stack": [...]}	Error no controlado. Las causas más frecuentes son omitir alguno de los cinco campos de información de referencia, omitir actividad u omitir moneda.

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.