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 } }, "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. "tipo_cedula": "01", "cedula": "601230456", "nombre": "Juan Rodríguez Mora", "correo": "jrodriguez@example.com", "nombre_comercial": "Finca La Esperanza" Campo Descripción tipo_cedula 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. 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. 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. 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. Por eso sus cinco primeros campos son obligatorios. Campo Descripción tipo_documento Obligatorio. Tipo del documento de referencia. Ver la tabla de tipos. numero_referencia Obligatorio. Número o identificador del documento de referencia, máximo 50 caracteres. codigo_referencia Obligatorio. Código que indica el motivo de la referencia. Ver la tabla de códigos. fecha_emision Obligatoria. Fecha del documento de referencia, en formato dd/mm/aaaa . razon_referencia Obligatoria. Descripción del motivo de la referencia, máximo 100 caracteres. tipo_documento_otro Obligatorio cuando tipo_documento es 99 . Entre 5 y 100 caracteres. codigo_referencia_otro Obligatorio cuando codigo_referencia es 99 . Entre 5 y 100 caracteres. 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 actividad string 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. codigo_actividad_receptor string Código de actividad económica del receptor. moneda string Código de moneda, por ejemplo CRC . 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. tipo_cedula , cedula , nombre , correo string Datos del vendedor. Ver la sección «El vendedor». tipo_documento , numero_referencia , codigo_referencia , fecha_emision , razon_referencia string Información de referencia. 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..detalle El código del medio de pago es 99 Texto entre 3 y 100 caracteres. otras_sennas_extranjero tipo_cedula es 05 Texto entre 5 y 300 caracteres. tipo_documento_otro tipo_documento es 99 Texto entre 5 y 100 caracteres. codigo_referencia_otro codigo_referencia es 99 Texto entre 5 y 100 caracteres. 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 durante el procesamiento. 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 .