{"id":19721214,"url":"https://github.com/unagisoftware/afip-invoices","last_synced_at":"2025-04-29T21:31:15.355Z","repository":{"id":39583258,"uuid":"401691154","full_name":"unagisoftware/afip-invoices","owner":"unagisoftware","description":"API para comunicación con AFIP para generación de comprobantes electrónicos","archived":false,"fork":false,"pushed_at":"2023-09-27T13:38:46.000Z","size":505,"stargazers_count":13,"open_issues_count":1,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-05T19:51:12.206Z","etag":null,"topics":["afip","afip-api","afip-facturas","rails","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/unagisoftware.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-08-31T12:15:48.000Z","updated_at":"2024-05-06T16:00:01.000Z","dependencies_parsed_at":"2023-02-08T19:46:27.079Z","dependency_job_id":null,"html_url":"https://github.com/unagisoftware/afip-invoices","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unagisoftware%2Fafip-invoices","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unagisoftware%2Fafip-invoices/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unagisoftware%2Fafip-invoices/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unagisoftware%2Fafip-invoices/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/unagisoftware","download_url":"https://codeload.github.com/unagisoftware/afip-invoices/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251585794,"owners_count":21613279,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["afip","afip-api","afip-facturas","rails","ruby"],"created_at":"2024-11-11T23:13:41.263Z","updated_at":"2025-04-29T21:31:10.344Z","avatar_url":"https://github.com/unagisoftware.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Testing Status](https://github.com/unagisoftware/afip-invoices/actions/workflows/rspec.yml/badge.svg?event=push)](https://github.com/unagisoftware/afip-invoices/actions/workflows/rspec.yml)\n[![Rubocop Status](https://github.com/unagisoftware/afip-invoices/actions/workflows/rubocop.yml/badge.svg?event=push)](https://github.com/unagisoftware/afip-invoices/actions/workflows/rubocop.yml)\n[![Coverage Status](https://coveralls.io/repos/github/unagisoftware/afip-invoices/badge.svg?branch=main)](https://coveralls.io/github/unagisoftware/afip-invoices?branch=main)\n\n## Introducción\n\nEsta aplicación Rails resuelve la integración con los [web services de AFIP](https://www.afip.gob.ar/ws/) a través de una API JSON. Permite mediante la gestión de entidades facturadoras la posibilidad generar y listar comprobantes. El presente README tiene por finalidad introducir sobre las tecnologías utilizadas, la puesta en marcha, el proceso de deploy y algunos diagramas de flujo para entender el funcionamiento interno de la API.\n\nLa aplicación está preparada para ser ejecutada tanto de forma tradicional como también utilizando Docker. A su vez, viene configurada con Capistrano lista para el deploy simplemente configurando algunas variables de entorno. Dentro de este README se decriben los comandos y las variables necesarias para tal propósito.\n\nAdemás de eso, este repositorio cuenta con una [wiki](https://github.com/unagisoftware/afip-invoices/wiki) en donde se puede encontrar más información relacionada a entender el funcionamiento de la API.\n\n## Contribuir\n\nEste es un proyecto open source, en el cual para que siga creciendo y mejorando necesitamos toda la ayuda posible. Nos podés ayudar desarrollando nuevas features, reportando errores, proponiendo ideas o simplemente siendo parte de la comunidad. En nuestra [guía de contribución](CONTRIBUTING.md) podés encontrar la información sobre cómo hacerlo.\n\n## Documentación de endpoints\n\n  [Ver documentación en Postman](https://documenter.getpostman.com/view/17046114/TzzHjXM3).\n\n## Dependencias\n\nLos pasos de configuración esperan que las siguientes herramientas se instalen en el sistema:\n* Ruby 2.7.6.\n* Rails 6.1.7.\n* PostgreSQL ([instalar con Docker](https://towardsdatascience.com/local-development-set-up-of-postgresql-with-docker-c022632f13ea)).\n\n## Setup inicial\n\n#### 1. Clonar el repositorio\n\n```bash\ngit clone git@github.com:unagisoftware/afip-invoices.git\n```\n\n#### 2. Crear el archivo `application.yml`\n\n##### 2.1 Copiar el archivo de ejemplo `application.yml.sample` y completar con los valores correctos.\n\n```bash\ncp config/application.yml.sample config/application.yml\n```\n\n##### 2.2 Crear y configurar el token de autorización y el salt para la encriptación de tokens de entidad\n\nPara crear el `AUTH_TOKEN` debés correr la siguiente tarea (copiá y pegá el valor resultante en tu `application.yml` o `.env` según corresponda):\n\n```ruby\nbundle exec rake credentials_generator:auth_token\n```\n\nPara crear el `ENCRYPTION_SERVICE_SALT` debés correr la siguiente tarea (copiá y pegá el valor resultante en tu `application.yml` o `.env` según corresponda):\n\n```ruby\nbundle exec rake credentials_generator:salt_encryptor\n```\n\n## Configuración y puesta en marcha\n\n### Sin Docker\n\n##### 1. Crear y configurar la base de datos\n\nCorrer los siguientes comandos para crear la base de datos y configuraciones (migraciones y seeds):\n\n```ruby\nbundle exec rake db:create\nbundle exec rake db:setup\n```\n\n##### 2. Correr los tests\n\n```ruby\nbundle exec rspec\n```\n##### 3. Verificar test coverage\n\n- Es necesario correr los tests para completar el reporte de coverage.\n- Abrir en tu navegador `coverage/index.html`.\n\n##### 4. Correr el servidor de Rails\n\nCorrer el siguiente comando, podés usar el parámetro `-p [puerto]` para cambiar el puerto en el que correr la aplicación:\n\n```ruby\nbundle exec rails server\n```\n\n### Con Docker\n\nLa aplicación utiliza Redis para almacenar en caché y no perder sus datos al apagar el contenedor.\n\n#### 1. Crear el archivo `.env`\n\nCopiar el archivo de ejemplo `application.yml.sample` y completar con los valores correctos.\n\nSeguir los pasos del paso 2.2 pero copiando los valores en el `.env`\n\n```bash\ncp .env.sample .env\n```\n\n#### 2. Crear y configurar la base de datos\n\n* Crear un volumen para persistir la información de nuestro PostgreSQL:\n\n    ```bash\n    docker volume create postgres-factura\n    ```\n\n* Correr los siguientes comando para crear y configurar la base de datos:\n\n  ```bash\n  docker-compose up -d db\n  docker-compose run -e MIGRATE='false' app bundle exec db:create\n  docker-compose run -e MIGRATE='false' app bundle exec db:setup\n  docker-compose down\n  ```\n\n#### 3. Correr los tests\n\n  ```bash\n  docker-compose up -d db\n  docker-compose run app bundle exec rspec\n  docker-compose down\n  ```\n#### 4. Correr la aplicación y el servicio de base datos\n\nSe corre un servidor Redis para no perder los datos de cache (cuando no se utiliza Docker la caché utilizada es el disco)\n\nCorrer el suguiente comando para correr los servicios (`app`, `postgresql` y `redis`):\n\n  ```bash\n  docker-compose up\n  ```\n\n## Caché en entorno de desarrollo\n\nPor cuestiones de optimización de consultas y de no invalidar credenciales de acceso provistas por la AFIP, la API cuenta con caché de información, la cual se invalida cada cierto tiempo en función del recurso que se almacene. Como la misma se encuentra deshabilitada por defecto en entorno de desarrollo, es necesario activarla con el siguiente comando:\n\n```bash\nbundle exec rails dev:cache\n```\n\nLa salida del comando anterior tiene que ser la siguiente:\n\n```bash\nDevelopment mode is now being cached.\n```\n\nEn caso de que la salida sea esta otra, entonces es necesario volver a ejecutar el comando:\n\n```bash\nDevelopment mode is no longer being cached.\n```\n\n## Deploy con Capistrano\n\nLa aplicación cuenta con la configuración necesaria para hacer deploy utilizando Capistrano. Para poder hacerlo funcionar, es necesario configurar algunas variables de entorno indicando parámetros relacionados a los servidores en donde se tiene que hacer el deploy. Por defecto, existentes configurados dos entornos: staging y producción.\n\nLas variables de entorno a agregar son las siguientes:\n- `APPLICATION_NAME`: Nombre de la aplicación (ejemplo: `afip-invoices`).\n- `PRODUCTION_SERVER_SSH_NAME`: Nombre del host de SSH del servidor de producción (ejemplo: `unagi-production`).\n- `REPO_URL`: Dirección del repositorio (ejemplo: `git@github.com:unagisoftware/afip-invoices.git`).\n- `SERVER_APPLICATION_DIRECTORY`: Directorio en donde se instala la aplicación en el servidor (ejemplo: `$HOME/apps/afip-invoices`).\n- `SERVER_PG_SYSTEM_DB`: Nombre de la DB del sistema en el servidor (ejemplo: `postgres`).\n- `SERVER_PG_SYSTEM_USER`: Usuario del sistema de la base de datos del servidor (ejemplo: `postgres`).\n- `SERVER_RBENV_BIN_PATH`: Dirección del ejecutable de rbenv en el servidor (ejemplo: `$HOME/.rbenv/bin/rbenv`).\n- `SERVER_USER`: Usuario del servidor (ejemplo: `deploy`).\n- `STAGING_SERVER_SSH_NAME`: Nombre del host de SSH del servidor de staging (ejemplo: `unagi-staging`).\n\nUna vez configuradas las variables de entorno para Capistrano, el primer deploy se realiza con los siguientes comandos (usar el entorno correspondiente, en este caso usaremos `staging`). Es importante que la clave SSH pública del servidor sea agregada al respositorio configurado en `REPO_URL` en caso de que sea privado para poder hacer un pull desde el servidor.\n\n```bash\ncap staging deploy:initial\ncap staging puma:make_dirs\ncap staging puma:config\ncap staging puma:systemd:config puma:systemd:enable\n```\n\nLuego, se creará en el directorio especificado en `SERVER_APPLICATION_DIRECTORY` del servidor un directorio con la configuración inicial de la aplicacción. En este momento, es necesario agregar las variables de entorno en `shared/config/application.yml` antes de hacer un deploy completo.\n\nLuego de agregarlas, el servidor quedará listo para cualquier deploy, el cual se realiza con el siguiente comando:\n\n```bash\ncap staging deploy\n```\n\n## Postman\n\nSe puede importar la colección de Postman con los endpoints del sistema. La misma se localiza en el siguiente path: `postman/api_afip.postman_collection.json`. [Aquí](https://learning.postman.com/docs/getting-started/importing-and-exporting-data/#importing-data-into-postman) podrás encontrar las intrucciones para importar una colección.\n\nPodés configurar un nuevo ambiente en Postman o bien [importar](https://learning.postman.com/docs/getting-started/importing-and-exporting-data/#importing-data-into-postman) el que se encuentra como ejemplo en el repositorio (`postman/environment_example.postman_environment.json`). Es necesario tener configuradas las siguientes variables de entorno:\n* `ADMIN_TOKEN`: el token de autorización que se utiliza para la gestión de entidades.\n* `TOKEN`: el token de alguna de las entidades configuradas.\n* `HOST`: el host o dominio donde correr tu aplicación (ejemplo http://localhost).\n\nPodés revisar la [documentación dentro de Postman](https://learning.postman.com/docs/publishing-your-api/documenting-your-api/#accessing-doc-views) o abrir el [siguiente link](https://documenter.getpostman.com/view/17046114/TzzHjXM3).\n\n## Diagramas de flujo\n\n### Crear un nuevo comprobante\n\n![Alta de comprobante](flowcharts/generar_comprobante.png?raw=true \"New Invoice\")\n\n### Autenticación contra la API de AFIP\n\n![Autenticación con AFIP](flowcharts/autenticacion_afip.png?raw=true \"AFIP autentication\")\n\n## Sobre Unagi\n\n![unagi](https://unagisoftware.com/wp-content/uploads/logo.svg)\n\n`afip-invoices` fue creada y es mantenida por Unagi. Los nombres y logos de Unagi son marcas registradas de Unagi SAS.\n\nSentimos un orgullo inmenso por colaborar con la comunidad open source. Visitá [nuestra web](https://unagisoftware.com) para ver algunos de nuestros proyectos más recientes o [escribinos](mailto:info@unagisoftware.com?subject=[GitHub]%20afip-invoice%20) para diseñar, desarrollar y hacer crecer tu proyecto junto a nuestro equipo.\n\n [Clutch](https://clutch.co/profile/unagi) | [Blog](https://medium.com/unagi) | [Instagram](https://www.instagram.com/unagisoftware/) | [Linkedin](https://www.linkedin.com/company/unagisoftware) | [Twitter](https://twitter.com/unagisoftware)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funagisoftware%2Fafip-invoices","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funagisoftware%2Fafip-invoices","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funagisoftware%2Fafip-invoices/lists"}