{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"1137da42-966f-450f-a606-c5753efae612","name":"OASIS-FEMH","description":"# Introducción\nAPI 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\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.\n\n\n# Resumen\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.\n\n# Autentificación\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:\n * Datos de autentificación del ATV: Consta de un usuario y contraseña, un archivo correspondiente a una llave criptográfica con la terminación de p12 y un pin de 4 números. Estos datos son proporcionados por el Ministerio de Hacienda a usuarios del ATV.\n * Datos del tributante: Son los datos que con los cuales el emisor de los documentos electrónicos se encuentra registrado ante el Ministerio de Hacienda y deben de enviarse en cada documento electrónico que se debe tributar. Consta de la siguiente campos:\n\t* Nombre del tributante\n\t* Identificación\n\t* Nombre comercial\n\t* Provincia \n\t* Cantón\n\t* Distrito\n\t* Barrio\n\t* Otras Señas\n\t* Número de Teléfono (si existe)\n\t* Número de Fax (si existe)\n\t* Correo Electrónico\n\n\nCon Provincia, Cantón y Distrito se debe utilizar el código de dos cifras establecido en el [documento de codificación de  ubicaciones](https://www.hacienda.go.cr/ATV/ComprobanteElectronico/docs/esquemas/2016/v4.1/Codificacion,canton,provincia,distritoybarrio.pdf) dado por el Ministerio de Hacienda.\n\n## Autentificación de ATV\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.   \n\n![Inicio](https://docs.google.com/uc?id=1cyCVYEVdXT2S9I0aot_L7Zyq6Qt5um0i)\n\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![Credenciales](https://docs.google.com/uc?id=1cuMI0zC4EZ2vScpFqYUheCGD7izaVURL)\n\n\nEl 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![Recuperar](https://docs.google.com/uc?id=19CrfBhKvkGDW4KuNmW9GQCuEpApRwinC)\n\n## Datos del Tributante\nEstos datos deben de aparecer en los campos correspondientes del emisor de la siguiente manera:\n\n        \"issuer\":{\n        \t\"name\": \"Nombre\",\n        \t\"identification_type\": \"Tipo de identificación\",\n        \t\"identification_number\": \"Número de Identificación\",\n        \t\"comercial_name\": \"Nombre Comercial\",\n        \t\"province\": \"Código de Provincia\",\n        \t\"canton\": \"Código de Cantón\",    \n        \t\"district\": \"Código de Distrito\",\n        \t\"neighborhood\": \"Código de Barrio\",\n        \t\"others\": \"Otras señas\",\n        \t\"phone_country_code\": \"Código de País\",\n        \t\"phone_number\": \"Número telefónico\",\n        \t\"fax_country_code\":\"Código de País\",\n        \t\"fax_number\":\"Número fax\",\n        \t\"email\": \"Correo Electrónico\"\n        }\n\n\n# Códigos de error \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.\n\n\n## Entre los errores por parte del API tenemos:\n\nCódigos\t\t| Status\t\t\t\t\t| Mensaje\n---\t\t\t|---\t\t\t\t\t\t|---\n422\t\t\t| `no_procesado`\t\t\t| Muestra el error por el cual no se proceso la petición, las causas se encuentran entre: errores por sintaxis, excederse de los caracteres establecidos o cifras incorrectas. \n401\t\t\t| `HTTP Token: Access denied.`\t| Existe algún problema con el token generado por el API.\n504 | `Gateway Timeout` | este error sucede cuando el sistema del Ministerio de Hacienda se encuentra en mantenimiento o con errores\n\n\n\n## Errores conocidos del Ministerio de Hacienda\n\nComprobantes Electrónicos API\n\nCódigos\t\t| Status\t\t\t\t\t| Mensaje\n---\t\t\t|---\t\t\t\t\t\t|---\n200\t\t\t| `Respuesta correcta`\t\t| Respuesta Correcta\n201\t\t\t| `Pendiente de revisión`\t|Se recibió correctamente el comprobante electrónico o respuesta del receptor, queda pendiente la validación del mismo y el envío de la respuesta de parte de Hacienda.\n206\t\t\t| `Respuesta Parcial`\t\t| Respuesta correcta parcial debido al uso de offset y/o limit.\n400\t\t\t| `Error en la validación`\t| Ocurrió algún error de validación.\n404\t\t\t| `No encontrado`\t\t| Ocurrió un error, no se encuentra el recurso.\n\n\n## Mensaje de respuesta del Ministerio de Hacienda:\nEl siguiente es la estructura de la respuesta retornada por el Ministerio de Hacienda a través de los servicios del API FEMH:\n\nNodo\t| Decripción\n---\t\t| ---\n`key` | Llave que identifica el documento electrónico en los sistemas del Ministerio de Hacienda, este se utiliza para comprobar el estado del mismo si es necesario\n`date` | Indica la fecha y hora en que se da la recepción del documento electrónico.\n`details` | Un campo de texto donde se detallan los errores que posee el documento en caso de tenerlos sino un mensaje que confirma la aceptación del documento.\n`consecutive` | Es un número que representa los documentos electrónicos\n`signed_xml` | Esta entrada posee un xml encriptado en base 64, posee el documento electrónico que fue recibido de parte del sistema del Ministerio de Hacienda.\n`response_xml` | esta entrada posee un xml encriptado en base 64, posee un mensaje de respuesta de parte del ATV sobre el documento electrónico enviado pero con más información.\n\n\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:\n\n\t\t<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n\t\t\t<MensajeHacienda xmlns=\"https://cdn.comprobanteselectronicos.go.cr/xml-schemas/v4.3/mensajeHacienda\">\n\t\t\t<Clave>50613051800310169054100100002040150416711174686700</Clave>\n\t\t\t<NombreEmisor>EJEMPLO S.A.</NombreEmisor>\n\t\t\t<TipoIdentificacionEmisor>02</TipoIdentificacionEmisor>\n\t\t\t<NumeroCedulaEmisor>1234567890</NumeroCedulaEmisor>\n\t\t\t<NombreReceptor>RECEPTOR EJEMPLO</NombreReceptor>\n\t\t\t<TipoIdentificacionReceptor>01</TipoIdentificacionReceptor>\n\t\t\t<NumeroCedulaReceptor>102340567</NumeroCedulaReceptor>\n\t\t\t<Mensaje>3</Mensaje>\n\t\t\t<DetalleMensaje>Este comprobante fue aceptado en el ambiente de pruebas, por lo cual no tiene validez para fines tributarios\n\n\t\t\tEl comprobante electrónico tiene los siguientes errores: \n\n\t\t\t[\n\t\t\tcodigo, mensaje, fila, columna\n\t\t\t-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\t\t\t]</DetalleMensaje>\n\t\t\t<MontoTotalImpuesto>520.0</MontoTotalImpuesto>\n\t\t\t<TotalFactura>15020.0</TotalFactura>\n\t\t\t\n\t\t\t\nEste es un ejemplo de como se visualiza en la respuesta `200 (OK)`:\n![200MH](https://docs.google.com/uc?id=1dYHXAc4kokp3LkDRLBUoA7J9mKwVymmQ)\n\nA 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](https://www.hacienda.go.cr/ATV/ComprobanteElectronico/docs/esquemas/2016/v4.3/ANEXOS%20Y%20ESTRUCTURAS_V4.3.pdf)\n\n\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 \n\n## Obligatoriedad\n\nObligatoriedad|Descripción\n---\t|---\nObligatorio | El dato debe estar en el documento siempre, independiente de las características de la transacción.\nCondicional |El dato no es obligatorio en todos los documentos, pero pasa a ser obligatorio en determinadas operaciones si se cumple una cierta condición. Por ejemplo:</br>- Si hay descuentos o recargos, éstos deben estar registrados porque en caso contrario los montos del documento son inconciliables, en relación con los montos netos, impuesto de ventas y Total.</br>- La información se encuentra condicionado a la existencia de la misma como por ejemplo impuestos de venta en un servicio o nombre comercial.</br>- Si en la factura se encuentra el dato el mismo debe de existir en las notas de crédito y débito.\nOpcional|Si la persona lo desea puede indicarlo\nInexistente|No debe de ser utilizado.\n\n\n## Envío de comprobantes electrónicos\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: \n\n * Comprobante 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![Encabezado](https://docs.google.com/uc?id=1ZzHZwAImPhiUiA9aFDSSpPfEB-StbHXJ)\n\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.\n * Respuesta 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.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"9097384","team":536855,"collectionId":"1137da42-966f-450f-a606-c5753efae612","publishedId":"SW7gVR3D","public":true,"publicUrl":"https://documenter-api.postman.tech/view/9097384/SW7gVR3D","privateUrl":"https://go.postman.co/documentation/9097384-1137da42-966f-450f-a606-c5753efae612","customColor":{"top-bar":"303030","right-sidebar":"303030","highlight":"EF5B25"},"documentationLayout":"classic-double-column","version":"8.10.0","publishDate":"2019-11-29T19:48:11.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{},"logos":{}},"statusCode":200},"environments":[{"name":"FEMH","id":"d70c41e9-76aa-481e-a6d5-cf579d6bfb4d","owner":"9097384","values":[{"key":"api_key","value":"CBW0QwG0RH3m2MuHg_jjHMcxbD32cG80","enabled":true}],"published":true}],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/c2567c7fa422bd5eb8ce81908fbae31a3ef6c10d7f0f6f7d46a021841d91201f","favicon":""},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"},{"label":"FEMH","value":"9097384-d70c41e9-76aa-481e-a6d5-cf579d6bfb4d"}],"canonicalUrl":"https://documenter.gw.postman.com/view/metadata/SW7gVR3D"}