API encargada de implementar las funciones de estructurado, firmado, envío y comprobación de documentos electrónicos en los servicios de la Administración de Tributación Virtual (ATV) establecidos por el Ministerio de Hacienda de Costa Rica. Además nuestra API se encarga de la generación y el envío de los comprobantes al receptor en caso de que solicite una factura electrónica. Nuestra API almacena los documentos enviados para que puedan ser consultados posteriormente además brinda la opción de la anulación[1] de documentos electrónicos previamente enviados y su posterior al receptor que se ha efectuado este proceso.
\n[1]Anulación: con respecto al funcionamiento del sistema del Ministerio de Hacienda de Costa Rica no existe una anulación real de un documento electrónico, el proceso que se sigue para cancelar es el uso de notas de crédito y débito que referencia a un documento electrónico (una factura electrónica o un tiquete electrónico). Su uso se explica más extendidamente más adelante.
\nUtilizando como entrada estructuras en formato json equivalente al documento electrónico que se desea tributar, el API FEMH convierte el archivo en un XML con el formato establecido en la versión 4.3 del Ministerio de Hacienda en cuanto a documentos electrónicos. El API también se encarga del firmado de dicho documento además de su envío y comprobación de estado.
\nEs necesario contar con información del tributante para acceder a los servicios de Administración de Tributación Virtual (ATV) del Ministerio de Hacienda de Costa Rica divididos en dos rubros:
\nCon Provincia, Cantón y Distrito se debe utilizar el código de dos cifras establecido en el documento de codificación de ubicaciones dado por el Ministerio de Hacienda.
\nSe utilizarán estos datos para que el API FEMH genere un token y con este se establezca la comunicación con los sistemas de ATV del Ministerio de Hacienda.
\nPara obtener el token se debe ingresar el usuario, contraseña y pin del tributante, además de cargar al sistema la llave criptográfica generada por la plataforma ATV. Además se habilita un campo para agregar el logo correspondiente a la empresa del emisor o persona jurídica, este logo se utilizará para agregarse al comprobante electrónico.\n
El token que se genera se debe ingresar el Entorno del API para realizar las pruebas en la variable de api_key y almacenarla en el sistema que desea incorporar el API FEMH para su posterior uso continuo. El token no tiene una expiración por lo cual no se debe generar constantemente pero en caso de necesitarlo se puede recuperar un nuevo token en la opción de recuperar token de acceso. Solo se deberá ingresar el usuario del tributante.\n
Estos datos deben de aparecer en los campos correspondientes del emisor de la siguiente manera:
\n \"issuer\":{\n \"name\": \"Nombre\",\n \"identification_type\": \"Tipo de identificación\",\n \"identification_number\": \"Número de Identificación\",\n \"comercial_name\": \"Nombre Comercial\",\n \"province\": \"Código de Provincia\",\n \"canton\": \"Código de Cantón\", \n \"district\": \"Código de Distrito\",\n \"neighborhood\": \"Código de Barrio\",\n \"others\": \"Otras señas\",\n \"phone_country_code\": \"Código de País\",\n \"phone_number\": \"Número telefónico\",\n \"fax_country_code\":\"Código de País\",\n \"fax_number\":\"Número fax\",\n \"email\": \"Correo Electrónico\"\n }\nExisten dos escenarios donde se pueden generar errores en los procesos con la utilización del API FEMH, un escenario es previo al envió de documentos electrónicos y el otro es posterior del envió de los mismos. El primer escenario son errores que son generados por parte del API debido a información en el cuerpo de la petición que sea incorrecta o mal calculada, el siguiente escenario son errores que son retornados por el mismo sistema del Ministerio de Hacienda, existe además una peculiaridad entre las respuestas del Ministerio de Hacienda ya que puede retornar respuestas 200 (OK) pero el documento electrónico puede ser rechazado en los sistemas del ente. Las causas de ellas son detalladas en las mismas respuestas por lo cual se debe prestar atención a este contenido.
Comprobantes Electrónicos API
\nEl siguiente es la estructura de la respuesta retornada por el Ministerio de Hacienda a través de los servicios del API FEMH:
\nEn el siguiente fragmento del response_xml ya decodficado podemos ver un ejemplo de la respuesta dada por el Ministerio de Hacienda en el ambiente de pruebas:
<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n <MensajeHacienda xmlns=\"https://cdn.comprobanteselectronicos.go.cr/xml-schemas/v4.3/mensajeHacienda\">\n <Clave>50613051800310169054100100002040150416711174686700</Clave>\n <NombreEmisor>EJEMPLO S.A.</NombreEmisor>\n <TipoIdentificacionEmisor>02</TipoIdentificacionEmisor>\n <NumeroCedulaEmisor>1234567890</NumeroCedulaEmisor>\n <NombreReceptor>RECEPTOR EJEMPLO</NombreReceptor>\n <TipoIdentificacionReceptor>01</TipoIdentificacionReceptor>\n <NumeroCedulaReceptor>102340567</NumeroCedulaReceptor>\n <Mensaje>3</Mensaje>\n <DetalleMensaje>Este comprobante fue aceptado en el ambiente de pruebas, por lo cual no tiene validez para fines tributarios\n\n El comprobante electrónico tiene los siguientes errores: \n\n [\n codigo, mensaje, fila, columna\n -99, \"La numeración consecutiva del comprobante que se esta utilizando para este archivo XML ya existe en nuestras bases de datos.\", 0, 0\n\n ]</DetalleMensaje>\n <MontoTotalImpuesto>520.0</MontoTotalImpuesto>\n <TotalFactura>15020.0</TotalFactura>\n \n \nEste es un ejemplo de como se visualiza en la respuesta 200 (OK):\n
A continuación se mostrará la información que debe contener la petición con el documento electrónico que se desea enviar. La información que se detalla a continuación esta explicita en varios documentos dados por el Ministerio de Hacienda pero como fuente principal se encuentra en Anexos y Estructuras 4.3
\nUn aspecto que se debe comprender es que los campos o nodos en la estructura de los documentos electrónicos tienen cierta obligatoriedad de aparecer y en otros casos posean cierta condición para que aparezcan. A continuación se definen los estados en cuanto a la obligatoriedad
\nUn requisito que debe cumplir un emisor, es que al solicitarle un receptor una factura electrónica se debe enviar un correo electrónico al emisor con los siguientes documentos:
\nComprobante electrónico: este comprobante corresponde a un recibo o factura impresa de la venta o el servicio prestado, el sistema generará este comprobante con un plantilla definida.\n
XML Firmado: corresponde el documento xml firmado que se envía a los sistemas del Ministerio de Hacienda, el receptor en ciertos casos debe presentarlo al mismo Ministerio de Hacienda para deducirlo como un gasto.
\nRespuesta de Hacienda: es un documento xml que posee la respuesta firmada del Ministerio de Hacienda que brinda información del documento recibido y su estado.
\nRealiza el envio de una Factura Electrónica al ATV. Se ejemplifica los siguientes casos de prueba:
\nPara realizar las pruebas se debe modificar por cada prueba que se efectue el campo number ya que corresponde al número consecutivo del documento y el Ministerio de Hacienda retorna un error si este consecutivo ya se encuentra registrado en su sistema.
Error:La numeración consecutiva del comprobante que se esta utilizando para este archivo XML ya existe en nuestras bases de datos\nRealiza el envio de una Factura Electrónica al ATV. Se ejemplifica los siguientes casos de prueba:
\nPara realizar las pruebas se debe modificar por cada prueba que se efectue el campo number ya que corresponde al número consecutivo del documento y el Ministerio de Hacienda retorna un error si este consecutivo ya se encuentra registrado en su sistema.
Error:La numeración consecutiva del comprobante que se esta utilizando para este archivo XML ya existe en nuestras bases de datos\nRealiza el envio de una Factura Electrónica al ATV. Esta ejemplifica un envío en moneda extranjera, para ello se expresan las cifras en el valor correspondiente. Posteriormente en el nodo de resumen (summary) en el campo moneda (currency) se utiliza la nomenclatura que se señala para la moneda, según el Ministerio de Hacienda. Además en el campo TipoCambio (exchange_rate) se ingresa el tipo de cambio con respecto al colón costarricense de la moneda anteriormente especificada.
\nPara realizar las pruebas se debe modificar por cada prueba que se efectue el campo number ya que corresponde al número consecutivo del documento y el Ministerio de Hacienda retorna un error si este consecutivo ya se encuentra registrado en su sistema.
Error:La numeración consecutiva del comprobante que se esta utilizando para este archivo XML ya existe en nuestras bases de datos\nA continuación se detallan las estructuras centrales que conforman el documento electrónico, estructuras como emisor, receptor, detalle de servicio, otros cargos y resumen de la factura son datos complejos por lo cual se estarán definiendo más adelante.
\n[1] Estos datos no existen explicitos en la estructura del documento que se envia al Ministerio de Hacienda pero se utilizan para generar la llave y el consecutivo que se enviara al Ministerio de Hacienda
\n[2] Aunque no se refleje directamente en el documento electrónico, es necesario su presencia en la petición
La información que posee el Receptor no difiere mucho con la del emisor, solo cuenta con un campo extra y la obligatoriedad es distinta en ciertas variables.
\nEspecifican los productos o servicios que se están facturando. La estructura que utiliza el Ministerio de Hacienda es la siguiente.
\nDetalleServicio\n LineaDetalle\n ...\n LineaDetalle\n ...\n LineaDetalle \n (...) \nLa estructura que se utiliza en la petición json es más simplificada para la comodidad del usuario utilizando un dato compuesto llamado items y dentro de llaves cada servicio o producto en una llave.
items{\n {...}\n {...}\n} \nSe detallan ahora los elementos que componen los Detalles de servicio.
\n[1] Actualmente se encuentra implementada pero al no existir la codificación a utilizar no se debe establecer en el JSON.
\n[2] CodigoComercial como dato complejo, su obligatoriedad es Opcional. Los campos comercial_code_type y comercial_code su obligatoriedad descrita es en caso de existir si el código comercial.
\n[3] Descuento como dato complejo, su obligatoriedad es Opcional. Los campos discount y discount_reason su obligatoriedad descrita es en caso de existir un descuento.
Realiza el envio de una Tiquete Electrónico al ATV. Se ejemplifica los siguientes casos de prueba:
\nPara realizar las pruebas se debe modificar por cada prueba que se efectue el campo number ya que corresponde al número consecutivo del documento y el Ministerio de Hacienda retorna un error si este consecutivo ya se encuentra registrado en su sistema.
Error:La numeración consecutiva del comprobante que se esta utilizando para este archivo XML ya existe en nuestras bases de datos\nRealiza el envio de una Tiquete Electrónico al ATV. Se ejemplifica los siguientes casos de prueba:
\nPara realizar las pruebas se debe modificar por cada prueba que se efectue el campo number ya que corresponde al número consecutivo del documento y el Ministerio de Hacienda retorna un error si este consecutivo ya se encuentra registrado en su sistema.
Error:La numeración consecutiva del comprobante que se esta utilizando para este archivo XML ya existe en nuestras bases de datos\nA continuación se detallan las estructuras centrales que conforman el documento electrónico, estructuras como emisor, receptor, detalle de servicio, otros cargos y resumen de la factura son datos complejos por lo cual se estarán definiendo más adelante.
\n[1] Estos datos no existen explicitos en la estructura del documento que se envia al Ministerio de Hacienda pero se utilizan para generar la llave y el consecutivo que se enviara al Ministerio de Hacienda
\n[2] Aunque no se refleje directamente en el documento electrónico, es necesario su presencia en la petición
Para el envío del tiquete electónico el receptor es condicional y la información que posee el Receptor no difiere mucho con la del emisor, solo cuenta con un campo extra y la obligatoriedad es distinta en ciertas variables.
\n[1] La ubicación en los datos del receptor es condicional. Pero de ser incluida una ubicación los campos de Provincia, Canton, Distrito y OtrasSenas son obligatorios. Por otra parte es condicional agregar el Barrio
\nEspecifican los productos o servicios que se están facturando. La estructura que utiliza el Ministerio de Hacienda es la siguiente.
\nDetalleServicio\n LineaDetalle\n ...\n LineaDetalle\n ...\n LineaDetalle \n (...) \nLa estructura que se utiliza en la petición json es más simplificada para la comodidad del usuario utilizando un dato compuesto llamado items y dentro de llaves cada servicio o producto en una llave.
items{\n {...}\n {...}\n} \nSe detallan ahora los elementos que componen los Detalles de servicio.
\n[1] Actualmente se encuentra implementada pero al no existir la codificación a utilizar no se debe establecer en el JSON.
\n[2] CodigoComercial como dato complejo, su obligatoriedad es Opcional. Los campos comercial_code_type y comercial_code su obligatoriedad descrita es en caso de existir si el código comercial.
\n[3] Descuento como dato complejo, su obligatoriedad es Opcional. Los campos discount y discount_reason su obligatoriedad descrita es en caso de existir un descuento.
Se encarga de enviar notas de débito
\nEl documento electrónico conocido como nota de débito se utiliza para realizar modificaciones a una factura electrónica o tiquete electrónico previamente enviado, se utiliza en casos que se debe aumentar las cifras de los montos o cantidad de los bienes o servicios que se hayan facturado. Se debe incluir los elementos que se desean modificar (lineas de detalle y otros cargos) además del nuevo resumen del comprobante.
\nLa nota de débito está compuesta de los siguientes campos:
\n[1] Estos datos no existen explicitos en la estructura del documento que se envia al Ministerio de Hacienda pero se utilizan para generar la llave y el consecutivo que se enviara al Ministerio de Hacienda
\n[2] Aunque no se refleje directamente en el documento electrónico, es necesario su presencia en la petición
La información que posee el Receptor no difiere mucho con la del emisor, solo cuenta con un campo extra y la obligatoriedad es distinta en ciertos campos. En las notas de débito este campo es condicional
\nEspecifican los productos o servicios que se están facturando. La estructura que utiliza el Ministerio de Hacienda es la siguiente.
\nDetalleServicio\n LineaDetalle\n ...\n LineaDetalle\n ...\n LineaDetalle \n (...) \nLa estructura que se utiliza en la petición json es más simplificada para la comodidad del usuario utilizando un dato compuesto llamado items y dentro de llaves cada servicio o producto en una llave.
items{\n {...}\n {...}\n} \nSe detallan ahora los elementos que componen los Detalles de servicio.
\n[1] Actualmente se encuentra implementada pero al no existir la codificación a utilizar no se debe establecer en el JSON.
\n[2] CodigoComercial como dato complejo, su obligatoriedad es Opcional. Los campos comercial_code_type y comercial_code su obligatoriedad descrita es en caso de existir si el código comercial.
\n[3] Descuento como dato complejo, su obligatoriedad es Opcional. Los campos discount y discount_reason su obligatoriedad descrita es en caso de existir un descuento.
El documento electrónico conocido como nota de crédito se utiliza para realizar modificaciones a una factura electrónica o tiquete electrónico previamente enviado, se utiliza en casos que se debe disminuir las cifras de los montos o cantidad de los bienes o servicios que se hayan facturado, además de anular el documento a que se referencia. Se debe incluir los elementos que se desean modificar (lineas de detalle y otros cargos) además del nuevo resumen del comprobante.
\nLa nota de débito está compuesta de los siguientes campos:
\n[1] Estos datos no existen explicitos en la estructura del documento que se envia al Ministerio de Hacienda pero se utilizan para generar la llave y el consecutivo que se enviara al Ministerio de Hacienda
\n[2] Aunque no se refleje directamente en el documento electrónico, es necesario su presencia en la petición
La información que posee el Receptor no difiere mucho con la del emisor, solo cuenta con un campo extra y la obligatoriedad es distinta en ciertos campos. En las notas de débito este campo es condicional
\nEspecifican los productos o servicios que se están facturando. La estructura que utiliza el Ministerio de Hacienda es la siguiente.
\nDetalleServicio\n LineaDetalle\n ...\n LineaDetalle\n ...\n LineaDetalle \n (...) \nLa estructura que se utiliza en la petición json es más simplificada para la comodidad del usuario utilizando un dato compuesto llamado items y dentro de llaves cada servicio o producto en una llave.
items{\n {...}\n {...}\n} \nSe detallan ahora los elementos que componen los Detalles de servicio.
\n[1] Actualmente se encuentra implementada pero al no existir la codificación a utilizar no se debe establecer en el JSON.
\n[2] CodigoComercial como dato complejo, su obligatoriedad es Opcional. Los campos comercial_code_type y comercial_code su obligatoriedad descrita es en caso de existir si el código comercial.
\n[3] Descuento como dato complejo, su obligatoriedad es Opcional. Los campos discount y discount_reason su obligatoriedad descrita es en caso de existir un descuento.
Para realizar las pruebas se debe modificar por cada prueba que se efectue el campo number ya que corresponde al número consecutivo del documento y el Ministerio de Hacienda retorna un error si este consecutivo ya se encuentra registrado en su sistema.
Error:La numeración consecutiva del comprobante que se esta utilizando para este archivo XML ya existe en nuestras bases de datos\nUna factura electrónica de exportación se utiliza en casos que se desea tributar bienes que se generen por medio de la exportación, a diferencia de una factura electrónica normal existen ciertos campos o nodos que no deben de estar presentes en estos documentos. A continuación se detallan las estructuras centrales que conforman el documento electrónico, estructuras como emisor, receptor, detalle de servicio, otros cargos y resumen de la factura son datos complejos por lo cual se estarán definiendo más adelante.
\n[1] Estos datos no existen explicitos en la estructura del documento que se envia al Ministerio de Hacienda pero se utilizan para generar la llave y el consecutivo que se enviara al Ministerio de Hacienda
\n[2] Aunque no se refleje directamente en el documento electrónico, es necesario su presencia en la petición
En el caso de receptor, no debe incluir Ubicación por lo cual no se debe agregar los campos de province, canton, district, neigborhood y others.
\nEspecifican los productos o servicios que se están facturando. La estructura que utiliza el Ministerio de Hacienda es la siguiente.
\nDetalleServicio\n LineaDetalle\n ...\n LineaDetalle\n ...\n LineaDetalle \n (...) \nLa estructura que se utiliza en la petición json es más simplificada para la comodidad del usuario utilizando un dato compuesto llamado items y dentro de llaves cada servicio o producto en una llave.
items{\n {...}\n {...}\n} \nSe detallan ahora los elementos que componen los Detalles de servicio. En caso de las facturas electrónicas de exportación no deben incluir productos con base imponible, por lo cual taxable_base no se debe incluir.
\n[1] Actualmente se encuentra implementada pero al no existir la codificación a utilizar no se debe establecer en el JSON.
\n[2] CodigoComercial como dato complejo, su obligatoriedad es Opcional. Los campos comercial_code_type y comercial_code su obligatoriedad descrita es en caso de existir si el código comercial.
\n[3] Descuento como dato complejo, su obligatoriedad es Opcional. Los campos discount y discount_reason su obligatoriedad descrita es en caso de existir un descuento.
En el caso de las facturas electrónicas de exportación los productos no pueden poseer exoneraciones, por lo cual el dato complejo exoneration no debe ser incluido.
\nSi es que existe otros cargos no se debe incluir la identidad de un tercero por lo cual los campos collector_id_number y collector_name no se deben incluir
\nYa que no es posible incluir exoneraciones en los productos los campos services_exonerate_total, goods_exonerate_total y exonerate_total no deben ser incluidos, incluyendo total_iva_returned ya que no existe la posibilidad de utilizar el campo de TotalIVADevuelto
\n","event":[{"listen":"prerequest","script":{"id":"4fd41fdf-660b-49a8-adcc-093a34f98f18","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"a1fc46da-a3f1-4511-96a7-f57f0a829da4","type":"text/javascript","exec":[""]}}],"_postman_id":"4c069956-ce75-4a3e-b4ad-912ceca9a74f"},{"name":"Factura Electrónica de Compra","item":[{"name":"Envio de factura electrónica de compra","id":"865124b2-112e-4d45-b3b8-049610d8d53a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"token":"{{api_key}}"},"isInherited":false},"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/json"},{"key":"Accept","type":"text","value":"application/json"}],"body":{"mode":"raw","raw":"{\n\t\"document\":{\n\t\t\"terminal\": \"00001\",\n\t\t\"headquarters\":\"001\",\n\t\t\"document_situation\": \"1\",\n\t\t\"number\": \"1111444777\",\n\t\t\"date_of_issue\": \"2020-01-22 15:30:00\",\n\t\t\"economic_activity\": \"521201\",\n\t\t\"issuer\":{\n\t\t\t\"name\": \"Contribuyente no emisor\",\n\t\t\t\"identification_type\": \"01\",\n\t\t\t\"identification_number\": \"100010001\",\n\t\t\t\"province\": \"1\",\n\t\t\t\"canton\": \"01\",\t\n\t\t\t\"district\": \"01\",\n\t\t\t\"neighborhood\": \"01\",\n\t\t\t\"others\": \"300 mts de la escuela\",\n\t\t\t\"phone_country_code\": \"506\",\n\t\t\t\"phone_number\": \"12345678\",\n\t\t\t\"email\": \"emisor@email.com\"\n\t\t},\n\t\t\"receiver\":{\n\t\t\t\"name\": \"DELAGUAYABA Sociedad Anonima\",\n\t\t\t\"identification_type\": \"02\",\n\t\t\t\"identification_number\": \"3101690541\",\n\t\t\t\"comercial_name\": \"DELAGUAYABA S.A.\",\n\t\t\t\"phone_country_code\": \"506\",\n\t\t\t\"phone_number\": \"83783386\",\n\t\t\t\"fax_country_code\":\"\",\n\t\t\t\"fax_number\":\"\",\n\t\t\t\"email\": \"facturaspruebas@delaguayaba.com\"\n\t\t},\n\t\t\"condition\":\"01\",\n\t\t\"credit_term\": \"\",\n\t\t\"payment_method\": \"02\",\n\t\t\"items\": [\n\t\t\t{\n\t\t\t\t\"comercial_code_type\": \"01\", \n\t\t\t\t\"comercial_code\": \"DN002\", \n\t\t\t\t\"quantity\" : \"2\",\n\t\t\t\t\"unit\" : \"Unid\",\n\t\t\t\t\"commercial_unit\": \"Unidad\", \n\t\t\t\t\"description\" : \"Base con ventilador Laptop\", \n\t\t\t\t\"unit_price\": \t\"10000.000\",\n\t\t\t\t\"total\" : \"20000.000\", \n\t\t\t\t\"subtotal\" : \"20000.000\", \n\t\t\t\t\"net_tax\":\"0.0\", \n\t\t\t\t\"net_total\":\"20000.000\"\n\t\t\t},\n\t\t\t{\n\t\t\t\t\"comercial_code_type\": \"04\", \n\t\t\t\t\"comercial_code\": \"ST001\", \n\t\t\t\t\"quantity\" : \"1\",\n\t\t\t\t\"unit\" : \"Sp\",\n\t\t\t\t\"commercial_unit\": \"Sp\", \n\t\t\t\t\"description\" : \"Soporte Tecnico 1h\", \n\t\t\t\t\"unit_price\": \"5000.000\",\n\t\t\t\t\"total\" : \"5000.000\", \n\t\t\t\t\"subtotal\" : \"5000.000\", \n\t\t\t\t\"taxes\": [{\"code\":\"01\", \"rate_code\":\"08\", \"rate\":\"13\", \"total\":\"650.000\"}],\n\t\t\t\t\"net_tax\":\"650.000\", \n\t\t\t\t\"net_total\":\"5650.000\"\n\t\t\t\n\t\t\t},\n\t\t\t{\n\t\t\t\t\"comercial_code_type\": \"04\", \n\t\t\t\t\"comercial_code\": \"ST001\", \n\t\t\t\t\"quantity\" : \"2\",\n\t\t\t\t\"unit\" : \"Sp\",\n\t\t\t\t\"commercial_unit\": \"Sp\", \n\t\t\t\t\"description\" : \"Instalación remota\", \n\t\t\t\t\"unit_price\": \"4400.000\",\n\t\t\t\t\"total\" : \"8801.000\", \n\t\t\t\t\"discount\":\"2200.000\",\n\t\t\t\t\"subtotal\" : \"6600.000\",\n\t\t\t\t\"discount_reason\": \"2do Mitad de precio\",\n\t\t\t\t\"net_tax\":\"0\", \n\t\t\t\t\"net_total\":\"6600.000\"\n\t\t\t},\n\t\t\t{\n\t\t\t\t\"comercial_code_type\": \"04\", \n\t\t\t\t\"comercial_code\": \"DN002\", \n\t\t\t\t\"quantity\" : \"2\",\n\t\t\t\t\"unit\" : \"Unid\",\n\t\t\t\t\"commercial_unit\": \"Unidad\", \n\t\t\t\t\"description\" : \"Camiseta de la empresa\", \n\t\t\t\t\"unit_price\": \t\"5000.000\",\n\t\t\t\t\"total\" : \"10000.000\", \n\t\t\t\t\"subtotal\" : \"10000.000\", \n\t\t\t\t\"taxes\": [\n\t\t\t\t\t{\"code\":\"01\", \"rate_code\":\"08\", \"rate\":\"13\", \"total\":\"1300.000\", \n\t\t\t\t\t\t\"exoneration\":{\t\n\t\t\t\t\t\t\t\"document_type\":\"01\", \n\t\t\t\t\t\t\t\"document_number\":\"OC-01\",\n\t\t\t\t\t\t\t\"institution\":\"Municipalidad\",\n\t\t\t\t\t\t\t\"date\":\"2019-09-05T00:49:52-06:00\",\n\t\t\t\t\t\t\t\"total_tax\":\"1300.000\", \n\t\t\t\t\t\t\t\"percentage\":\"100\" }\t\n\t\t\t\t\t}\n\t\t\t\t\t],\n\t\t\t\t\"net_tax\":\"0.0\", \n\t\t\t\t\"net_total\":\"10000.000\"\n\t\t\t}\n\t\t\t\n\t\t\t\n\t\t\t],\n\t\t\"summary\":{\n\t\t\t\"currency\":\"CRC\",\n\t\t\t\"exchange_rate\":\"1\",\n\t\t\t\"services_taxable_total\": \"5000.00\",\n\t\t\t\"services_exent_total\": \"8800.00\",\n\t\t\t\"services_exonerate_total\":\"\",\n\t\t\t\"goods_taxable_total\":\"\",\n\t\t\t\"goods_exent_total\":\"20000.000\",\n\t\t\t\"goods_exonerate_total\":\"10000.000\",\n\t\t\t\"taxable_total\": \"5000.00\",\n\t\t\t\"exent_total\":\"28800.00\",\n\t\t\t\"exonerate_total\":\"10000.00\",\n\t\t\t\"subtotal\":\"43800.00\",\n\t\t\t\"discount_total\":\"2200.000\",\n\t\t\t\"gross_total\":\"41600.00\",\n\t\t\t\"tax_total\":\"650.00\",\n\t\t\t\"net_total\":\"42250.00\"\n\t\t},\n\t\t\"references\":[{\n\t\t\t\"document_type\":\"14\",\n\t\t\t\"number\": \"1111444671\",\n\t\t\t\"date\":\"2020-01-21 15:30:00\",\n\t\t\t\"code\": \"04\",\n\t\t\t\"reason\": \"Compra extraordinaria durante una gira\"\n\t\t}]\n\t}\n}"},"url":"http://localhost:3000/v1/documents/purchase_invoice","description":"Realiza el envío de una Factura electrónica de compra a los sistemas del ATV.
\nAclaración: Para las pruebas se necesita colocar un emisor que cumpla con los requisitos de este documento ya que caso contrario la emisión será rechazada, durante las pruebas internas se proporciono un emisor con dichas condiciones (contribuyente no obligado a emitir comprobantes electrónicos) pero por la seguridad de este no se mantiene la información permanentemente en esta documentación. Además se modifican la clave númerica, el cuerpo y las respuestas en los ejemplos y la petición para que no use información personal del contribuyente no emisor.
\nPara realizar las pruebas se debe modificar por cada prueba que se efectue el campo number ya que corresponde al número consecutivo del documento y el Ministerio de Hacienda retorna un error si este consecutivo ya se encuentra registrado en su sistema.
Error:La numeración consecutiva del comprobante que se esta utilizando para este archivo XML ya existe en nuestras bases de datos\nEl Ministerio de Hacienda establece sobre la factura electrónica de compra lo siguiente:
\nEn cuanto a la información del emisor (el contribuyente excluido de emitir comprobantes electrónicos) se le debe solicitar la misma información que posee una Factura Electrónica tradicional para emitir el documento, más adelante se especifican los componentes del emisor (issuer) para que se tenga en referencia pero además de solicitarle la actividad económica con la cual tiene registrado su negocio. Si la información del receptor es incorrecta o no cumple con los requisitos para este tipo de documento electrónico se rechazará.
\nAhora bien los datos propios del contribuyente deben aparecer ubicados en los datos del receptor (ya que en este caso se cumple con ese papel ya que es un bien o servicio se tramita como un gasto o costo) pero en cuanto a la obligatoriedad de sus componentes comparte las mismas condiciones en las facturas electrónicas tradicionales, es decir la obligatoriedad de la ubicación del receptor es condicional.
\nOtros campos que se deben incluir en esta factura electrónica es una referencia con la siguiente información específica, en este caso es obligatorio todos los campos.
\nA continuación se detallan las estructuras centrales que conforman el documento electrónico, estructuras como emisor, receptor, detalle de servicio, otros cargos y resumen de la factura son datos complejos por lo cual se estarán definiendo más adelante.
\n[1] Estos datos no existen explicitos en la estructura del documento que se envia al Ministerio de Hacienda pero se utilizan para generar la llave y el consecutivo que se enviara al Ministerio de Hacienda
\n[2] Aunque no se refleje directamente en el documento electrónico, es necesario su presencia en la petición
La información que posee el Receptor no difiere mucho con la del emisor, solo cuenta con un campo extra y la obligatoriedad es distinta en ciertas variables.
\nEspecifican los productos o servicios que se están facturando. La estructura que utiliza el Ministerio de Hacienda es la siguiente.
\nDetalleServicio\n LineaDetalle\n ...\n LineaDetalle\n ...\n LineaDetalle \n (...) \nLa estructura que se utiliza en la petición json es más simplificada para la comodidad del usuario utilizando un dato compuesto llamado items y dentro de llaves cada servicio o producto en una llave.
items{\n {...}\n {...}\n} \nSe detallan ahora los elementos que componen los Detalles de servicio.
\n[1] Actualmente se encuentra implementada pero al no existir la codificación a utilizar no se debe establecer en el JSON.
\n[2] CodigoComercial como dato complejo, su obligatoriedad es Opcional. Los campos comercial_code_type y comercial_code su obligatoriedad descrita es en caso de existir si el código comercial.
\n[3] Descuento como dato complejo, su obligatoriedad es Opcional. Los campos discount y discount_reason su obligatoriedad descrita es en caso de existir un descuento.
Funcionalidad que consulta el estado de un documento electrónico enviado a los sistemas del Ministerio de Hacienda. Se debe utilizar la llave o key que es generada en el xml para consultar el estado de ese documento.
Se debe colocar en la url de la siguiente manera .../documents/status/key para realizar la consulta a los sistemas del Ministerio de Hacienda
Consulta los documentos electrónicos de un determinado usuario que hayan sido previamente almacenados en la base de datos de FEMH. Seutiliza una autorización Bearer Token con el token generado por FEMH.
\nEl arreglo de documentos electrónicos que se retornan poseen los siguientes valores:
\n","urlObject":{"protocol":"http","port":"3000","path":["v1","electronic_documents",""],"host":["localhost"],"query":[],"variable":[]}},"response":[{"id":"e728151b-66c2-4e0f-a7ba-0cba72c88bae","name":"200 OK - Sin documentos almacenados","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":"http://localhost:3000/v1/electronic_documents/"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"ETag","value":"W/\"4f53cda18c2baa0c0354bb5f9a3ecbe5\""},{"key":"Cache-Control","value":"max-age=0, private, must-revalidate"},{"key":"X-Request-Id","value":"0246ac96-45e1-42c3-9350-83f5982180e1"},{"key":"X-Runtime","value":"2.590793"},{"key":"Transfer-Encoding","value":"chunked"}],"cookie":[],"responseTime":null,"body":"[]"},{"id":"f1fc9029-9e9f-43da-87e0-52ea23475c33","name":"401 Acceso no autorizado (Token)","originalRequest":{"method":"GET","header":[{"key":"Content-Type","type":"text","value":"application/json"},{"key":"Accept","type":"text","value":"application/json"}],"url":"http://localhost:3000/v1/electronic_documents/"},"status":"Unauthorized","code":401,"_postman_previewlanguage":"plain","header":[{"key":"WWW-Authenticate","value":"Token realm=\"Application\""},{"key":"Content-Type","value":"text/plain; charset=utf-8"},{"key":"Cache-Control","value":"no-cache"},{"key":"X-Request-Id","value":"2e60f012-92a5-451f-a176-ff43c794d401"},{"key":"X-Runtime","value":"0.064092"},{"key":"Transfer-Encoding","value":"chunked"}],"cookie":[],"responseTime":null,"body":"HTTP Token: Access denied.\n"},{"id":"f8b12aa5-e1b8-415c-81ed-1ed9339f2908","name":"200 OK - Documentos creados","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":"http://localhost:3000/v1/electronic_documents/"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"ETag","value":"W/\"1895eaea50f91f8640e8b9e40625b498\""},{"key":"Cache-Control","value":"max-age=0, private, must-revalidate"},{"key":"X-Request-Id","value":"24fa59f6-1dd3-4f64-b254-81d7163a47a8"},{"key":"X-Runtime","value":"0.020130"},{"key":"Transfer-Encoding","value":"chunked"}],"cookie":[],"responseTime":null,"body":"[\n {\n \"id\": 6,\n \"created_at\": \"2020-02-19T09:14:30.386-06:00\",\n \"status\": \"aceptado\",\n \"document_key\": \"50613051800310169054100100002011111444707129673084\",\n \"consecutive\": \"00100002011111444707\",\n \"doc_type\": \"01\",\n \"detail_mh\": \"Este comprobante fue aceptado en el ambiente de pruebas, por lo cual no tiene validez para fines tributarios\",\n \"receiver\": \"Keylor Vargas\",\n \"currency\": \"USD\",\n \"net_total\": \"8.000\"\n },\n {\n \"id\": 5,\n \"created_at\": \"2020-02-19T09:11:46.413-06:00\",\n \"status\": \"aceptado\",\n \"document_key\": \"50613051800310169054100100002011111444705198708842\",\n \"consecutive\": \"00100002011111444705\",\n \"doc_type\": \"01\",\n \"detail_mh\": \"Este comprobante fue aceptado en el ambiente de pruebas, por lo cual no tiene validez para fines tributarios\",\n \"receiver\": \"Keylor Vargas\",\n \"currency\": \"USD\",\n \"net_total\": \"8.000\"\n },\n {\n \"id\": 4,\n \"created_at\": \"2020-02-19T09:10:30.491-06:00\",\n \"status\": \"aceptado\",\n \"document_key\": \"50613051800310169054100100002011111444704111949716\",\n \"consecutive\": \"00100002011111444704\",\n \"doc_type\": \"01\",\n \"detail_mh\": \"Este comprobante fue aceptado en el ambiente de pruebas, por lo cual no tiene validez para fines tributarios\",\n \"receiver\": \"Keylor Vargas\",\n \"currency\": \"USD\",\n \"net_total\": \"8.000\"\n },\n {\n \"id\": 3,\n \"created_at\": \"2020-02-19T09:09:54.465-06:00\",\n \"status\": \"aceptado\",\n \"document_key\": \"50613051800310169054100100002011111444703114881151\",\n \"consecutive\": \"00100002011111444703\",\n \"doc_type\": \"01\",\n \"detail_mh\": \"Este comprobante fue aceptado en el ambiente de pruebas, por lo cual no tiene validez para fines tributarios\",\n \"receiver\": \"Keylor Vargas\",\n \"currency\": \"USD\",\n \"net_total\": \"8.000\"\n },\n {\n \"id\": 2,\n \"created_at\": \"2020-02-19T09:03:52.303-06:00\",\n \"status\": \"aceptado\",\n \"document_key\": \"50613051800310169054100100002011111444701178897516\",\n \"consecutive\": \"00100002011111444701\",\n \"doc_type\": \"01\",\n \"detail_mh\": \"Este comprobante fue aceptado en el ambiente de pruebas, por lo cual no tiene validez para fines tributarios\",\n \"receiver\": \"Keylor Vargas\",\n \"currency\": \"USD\",\n \"net_total\": \"8.000\"\n },\n {\n \"id\": 1,\n \"created_at\": \"2020-02-19T09:03:13.676-06:00\",\n \"status\": \"aceptado\",\n \"document_key\": \"50613051800310169054100100002011111444700188744694\",\n \"consecutive\": \"00100002011111444700\",\n \"doc_type\": \"01\",\n \"detail_mh\": \"Este comprobante fue aceptado en el ambiente de pruebas, por lo cual no tiene validez para fines tributarios\",\n \"receiver\": \"Keylor Vargas\",\n \"currency\": \"USD\",\n \"net_total\": \"8.000\"\n }\n]"}],"_postman_id":"4a712c75-387d-4985-9d44-b21cc4c1dc29"},{"name":"Anular factura electrónica","id":"9c7b1845-7088-46e2-88a8-7b45e4ffee88","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"token":"{{api_key}}"},"isInherited":false},"method":"GET","header":[{"key":"Content-Type","type":"text","value":"application/json"},{"key":"Accept","type":"text","value":"application/json"}],"url":"http://localhost:3000/v1/electronic_documents/nullify/20","description":"Por medio del ID del documento electrónico (previamente consultado por medio de la petición Consultar documentos por usuario) se genera manualmente una nota de crédito en referencia del documento electrónico correspondiente a la ID enviada. La ID del documento se envía en el url de la petición
\n[1] Se debe tomar en cuenta que este servicio se realiza asistido por una interfaz gráfica en OASIS por lo cual el envío en más una ocasión de la anulación por este medio a un documento al que previamente se anuló genera mensaje de rechazo del Ministerio de Hacienda(consecutivo repetido). Esto error solo es provocado por medios manuales ya que se en esta interfaz se bloquea este servicio cuando fue previamente anulado.
\nEl arreglo de documentos electrónicos que se retornan poseen los siguientes valores:
\n","urlObject":{"protocol":"http","port":"3000","path":["v1","electronic_documents","nullify","20"],"host":["localhost"],"query":[],"variable":[]}},"response":[{"id":"09b4d5bb-6316-4b64-b824-8d6bfc118942","name":"404 - Documento electrónico no encontrado","originalRequest":{"method":"GET","header":[{"key":"Content-Type","type":"text","value":"application/json"},{"key":"Accept","type":"text","value":"application/json"}],"url":"http://localhost:3000/v1/electronic_documents/nullify/99"},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json; charset=UTF-8"},{"key":"X-Request-Id","value":"531cf2ea-1b6c-4e89-b98e-b8f5bb847e75"},{"key":"X-Runtime","value":"2.093585"},{"key":"Content-Length","value":"11729"}],"cookie":[],"responseTime":null,"body":"{\n \"status\": 404,\n \"error\": \"Not Found\",\n \"exception\": \"#