rbbsoft / arca-sdk
SDK PHP PSR-4 standalone para facturacion electronica contra ARCA (WSAA + WSFE).
Requires
- php: >=8.1
- ext-bcmath: *
- ext-gd: *
- ext-libxml: *
- ext-openssl: *
- ext-pdo_mysql: *
- ext-simplexml: *
- ext-soap: *
- mpdf/mpdf: ^8.3
- mpdf/qrcode: ^1.2
- psr/log: ^1.1 || ^2.0 || ^3.0
Requires (Dev)
- phpdocumentor/phpdocumentor: ^3.10
- phpunit/phpunit: ^10.5
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
SDK PHP PSR-4 standalone para facturación electrónica contra ARCA (ex AFIP). Autenticación WSAA y factura electrónica WSFE para Facturas A/B/C/M y Notas de Crédito A/B/C/M, con idempotencia atómica, recuperación de zombies y retry policy incluidos.
- Guía de uso completa: docs/GUIA_DE_USO.md
- Mantenimiento del proyecto (auditor docs ↔ código, etc.): docs/MAINTENANCE.md
- Historial de versiones: CHANGELOG.md
- Manuales oficiales de ARCA: docs/ARCA/
- Estado: v2.0.0 — single-tenant, un CUIT por proceso PHP-FPM. Multi-tenant está explícitamente fuera de alcance.
Quickstart
use Rbbsoft\ArcaSdk\ArcaSdk; use Rbbsoft\ArcaSdk\Config\Config; $config = Config::fromArray([ 'env' => 'homo', 'cuit' => '<CUIT_EMISOR>', 'punto_venta' => 1, 'cert_path' => 'C:\xampp\Certificados\MiCertificado.pem', 'key_path' => 'C:\xampp\Certificados\MiClavePrivada.key', 'db_dsn' => 'mysql:host=127.0.0.1;dbname=arca_facturador;charset=utf8mb4', 'db_user' => 'arca_user', 'db_pass' => '...', ]); $arca = ArcaSdk::getInstance($config); $respuesta = $arca->emitirFactura('a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d', [ 'concepto' => 1, 'receptor_documento_tipo' => 80, 'receptor_documento_nro' => '<CUIT_RECEPTOR>', 'receptor_condicion_iva' => 'RI', 'mon_id' => 'PES', 'mon_cotiz' => '1.00', 'items' => [ ['importe_gravado' => '1000000.00', 'alicuota_iva' => '21'], ], ]); echo $respuesta->cae;
Para la instalación detallada, las variables de entorno, los códigos de error, el diagnóstico, las operaciones administrativas y todo lo demás, ver la guía de uso completa.
Plantilla visual estilo ARCA (v0.7.0+)
Desde v0.7.0 el SDK puede generar PDFs con una plantilla visual completa que replica la estructura de un comprobante ARCA real (basada en el template "RBB Autoradio"), además del layout mínimo retrocompatible de v0.6.x. Se activa pasando un ComprobantePdfMetadata como 3er parámetro de ComprobantePdfGenerator::generar() (o de ArcaSdk::generarPdf()). Los datos del emisor se obtienen por Padrón A13 (obtenerEmisor()); los datos que ARCA no expone se completan manualmente (nombre de fantasía, ingresos brutos, inicio de actividades, condición IVA, nombre del receptor, etc.). Documentación completa y ejemplo en docs/GUIA_DE_USO.md §3.6 y examples/factura_c_basica_pdf_plantilla.php. La denominación y la letra se resuelven por tipo de comprobante; el IVA se muestra cuando está informado. La referencia visual principal es Factura C.
Previsualización local del PDF
No se necesitan certificados, base de datos ni acceso a ARCA para probar el diseño:
php examples/previsualizar_pdf.php php examples/previsualizar_pdf.php 40 vendor/bin/phpunit tests/unit/Pdf tests/unit/Wsfe/ComprobanteEmitidoTest.php
Las muestras se guardan en comprobantes/previews/, con datos ficticios y una leyenda sin validez fiscal. La segunda incluye varias páginas por copia. Se requieren pdftotext de Poppler para las pruebas que inspeccionan el contenido del PDF.
El nombre automático ahora es {cuit}_{tipo:03}_{puntoVenta:05}_{numero:08}.pdf para evitar colisiones entre puntos de venta. Se puede seguir pasando un nombre explícito sin ruta. La salida se reemplaza atómicamente. ComprobantePdfMetadata permite una, dos o tres copias, condicionVenta explícita y una leyenda opcional; valida que los importes comerciales concuerden con el detalle autorizado. Los números aceptan punto o coma decimal, sin separadores de miles.
Regeneración de PDF
Una vez que ARCA asigna un CAE a un comprobante, esa emisión es inmutable (idempotencia atómica). Pero el PDF generado por el SDK puede necesitar regenerarse en estos casos:
- El layout v0.7.0+ (plantilla visual estilo ARCA real) se desarrolló después de varias emisiones reales. Los PDFs emitidos con la plantilla v0.6.x quedaron con el layout mínimo retrocompatible. Este script permite volver a emitirlos con el layout nuevo conservando el mismo CAE.
- Cambian datos manuales del emisor/receptor (por ejemplo, se completa el nombre de fantasía después de una primera emisión, o se corrige la condición IVA). No amerita pedir un CAE nuevo a ARCA: solo se regenera el PDF con los datos actualizados del
ComprobantePdfMetadata. - El PDF original se perdió del filesystem (borrado accidental, deploy que no incluye
comprobantes/— directorio gitignored). La fuente de verdad para el comprobante es la tablaarca_emisiones_idempotenciadel SDK; el PDF se reconstruye a partir de los datos almacenados.
ARCA no conserva un "PDF maestro": el comprobante electrónico es el CAE + el QR + el JSON del response. El PDF es materialización local para impresión o entrega al receptor. Regenerarlo es siempre seguro; volver a emitir contra ARCA no lo es (asignaría un CAE nuevo).
El script examples/regenerar_pdf_plantilla.php hace exactamente esto: lee un array merge típico con los datos del comprobante autorizado, construye un ComprobanteEmitido inmutable vía ComprobanteEmitido::fromArray(), le pasa un ComprobantePdfMetadata con la metadata v0.7.0, y sobreescribe comprobantes/{cbte_tipo}-{cbte_nro}.pdf con el layout completo (3 páginas, tildes, formato 90000,00 sin separador de miles, DNI sin puntos, COD. 011 uppercase, banda "RBB AUTORADIO" italic+quotes, etc.). El script es local y offline — no habla con ARCA.
Uso:
php examples/regenerar_pdf_plantilla.php
El array $mergeDemo y el ComprobantePdfMetadata están embebidos como demo del comprobante 11-29 (Factura C, Pto Vta 2, CUIT emisor 20940361444, CAE 86320746470438). Para regenerar otro comprobante, editar esas dos variables con los datos del comprobante autorizado (los reales vienen de la tabla de idempotencia del SDK o del sistema del operador).
Instalación
El SDK se distribuye vía Composer como rbbsoft/arca-sdk. Requisitos: PHP 8.1 o superior con las extensiones ext-soap, ext-bcmath, ext-openssl y ext-pdo_mysql.
Para integrarlo a un proyecto existente:
composer require rbbsoft/arca-sdk
Para probarlo de forma aislada (crea un directorio nuevo con el SDK y todas sus dependencias; incluye la suite como composer test):
composer create-project rbbsoft/arca-sdk test-install cd test-install composer test # suite general; ver requisitos y limitaciones debajo
La configuración del .env, los certificados y la base de datos se documentan en la guía de uso completa, sección 6.
Validación en entorno de homologación (ARCA)
El SDK se prueba de manera regular contra el entorno de homologación de ARCA (wsfev1 homo, https://wswhomo.afip.gov.ar/...). La homologación es un ambiente de prueba provisto por ARCA que replica los contratos y reglas de validación del ambiente productivo, pero no tiene validez fiscal y no se persiste más allá de un periodo breve.
La validación cubre dos ejes:
-
Suite automatizada de tests: 614 tests / 2920 assertions, sin errores, fallos ni omisiones en PHP 8.3.6 y MariaDB aislada (16/11/2026). Incluye PDF real, XML, WSAA con certificado temporal, persistencia y concurrencia. Las llamadas a ARCA usan dobles.
bash tests/run-mysql.shcrea y elimina su propia base temporal, sin red ni credenciales reales; requiere MariaDB instalado.composer testusa una base configurada conARCA_TEST_DSN,ARCA_TEST_USERyARCA_TEST_PASS; sin MySQL las pruebas de integración se omiten. -
Emisión real de los ocho tipos de comprobante soportados mediante los scripts de
examples/. Cada invocación genera un comprobante con CAE asignado por ARCA homologación, persistido enarca_emisiones_idempotencia. Los tipos validados son:
| Tipo de comprobante | Código | Total | CAE asignado por ARCA homo |
|---|---|---|---|
| Factura A | 1 | 121,00 | 86310728860034 |
| Factura B | 6 | 121,00 | 86310728860050 |
| Factura C | 11 | 100,00 | 86310728860063 |
| Factura M | 51 | 100,00 | 86310728860089 |
| Nota de Crédito A | 3 | 121,00 | 86310728860092 |
| Nota de Crédito B | 8 | 121,00 | 86310728860123 |
| Nota de Crédito C | 13 | 100,00 | 86310728860136 |
| Nota de Crédito M | 53 | 100,00 | 86310728860152 |
Las emisiones se realizaron con punto de venta 2, CUIT emisor y CUIT receptor configurados por el operador en su .env (variables ARCA_CUIT y ARCA_CUIT_RECEPTOR) y fecha 2026-08-04. La sección 0 de la guía de uso documenta el contrato de las variables de entorno. Los CUITs reales no se versionan en el repositorio.
Para reproducir la validación:
# Suite automatizada composer install bash tests/run-mysql.sh # Emisión real de un comprobante contra ARCA homologación # (requiere .env configurado y certificados en el path declarado) php examples/factura_a_basica.php 0 1 0
Alcance de la validación: el SDK se considera validado únicamente en el entorno de homologación descripto. No se ha emitido contra el ambiente productivo de ARCA; la presente versión (v2.0.0) no se encuentra en producción. Antes de cualquier pase a producción se requiere una corrida de homologación con el CUIT y el punto de venta definitivos, junto con la verificación manual de los CAE resultantes.
Actualización a v2.0.0
Antes de usar resetExternalId(), ejecutar php db/migrate.php contra la base del SDK. Agrega arca_reset_audit de forma idempotente; no elimina emisiones. El reset toma el mismo bloqueo de emisión y una transacción con SELECT FOR UPDATE: copia la fila a auditoría y la borra en una sola confirmación. Si no puede auditar, aborta. Respaldar ambas tablas; el usuario del SDK necesita INSERT en auditoría, sin permisos de UPDATE ni DELETE sobre ella.
Para servicios (concepto 2/3), informar las tres fechas: servicio_desde, servicio_hasta y vencimiento_pago. Los otros tributos requieren el detalle tributos; el total puede derivarse del detalle. A/B/M calculan IVA sobre la base agrupada por alícuota. Los ítems mantienen el orden comercial y el fingerprint ordena una copia para conservar la compatibilidad de solicitudes anteriores sin tributos.
Los ejemplos reutilizan el UUID durante los reintentos; para continuar la misma operación en otra ejecución, pasar el UUID impreso como ARCA_EXTERNAL_ID. No generar otro UUID después de perder una respuesta.
La recuperación idempotente conserva moneda, cotización, receptor e ítems. Las respuestas antiguas parciales se completan desde request_json; respuestas sin importes autorizados fallan de forma explícita. Una recuperación con distinto concepto, desglose o fechas de servicio se rechaza.
phpDocumentor se retiró de require-dev porque exige Flysystem 1.x afectado por CVE-2026-102601. phpdoc.xml se conserva como configuración para una herramienta externa; vendor/bin/phpdoc deja de instalarse. composer audit --locked no informa avisos en la instalación verificada. composer.lock sigue excluido de Git por la política del proyecto.
Estructura
ARCASdk/
├── .env.example
├── .gitignore
├── CHANGELOG.md
├── composer.json
├── db/
│ └── migrate.php ← CLI de migración
├── docs/ ← manuales y mantenimiento
│ ├── ARCA/ ← referencias oficiales
│ │ ├── ADMINREL_Delegar_Webservices.pdf
│ │ ├── INDICE.md
│ │ ├── QRespecificaciones.pdf
│ │ ├── WSAA_asociar_certificado_a_wsn_produccion.pdf
│ │ ├── WSAA_Especificacion_Tecnica_1.2.2.pdf
│ │ ├── WSAA_Generacion_certificados_digitales.pdf
│ │ ├── WSAA_manual_desarrollador.pdf
│ │ ├── WSAA_obtener_certificado_produccion.pdf
│ │ ├── WSASS_como_adherirse.pdf
│ │ ├── WSASS_manual.pdf
│ │ └── WSFEv1_Manual_Desarrollador_v4.5_ARCA.pdf
│ ├── GUIA_DE_USO.md
│ └── MAINTENANCE.md
├── examples/
│ ├── factura_a_basica.php
│ ├── factura_b_basica.php
│ ├── factura_c_basica.php
│ ├── factura_c_basica_pdf.php
│ ├── factura_c_basica_pdf_plantilla.php
│ ├── factura_m_basica.php
│ ├── nota_credito_a_basica.php
│ ├── nota_credito_b_basica.php
│ ├── nota_credito_c_basica.php
│ ├── nota_credito_m_basica.php
│ ├── previsualizar_pdf.php ← muestras offline con datos ficticios
│ ├── regenerar_pdf_plantilla.php
│ └── reset_admin.php
├── LICENCIA.md
├── LICENSE
├── phpdoc.xml
├── phpunit.xml
├── README.md
├── sql/
│ └── schema.sql ← esquema MySQL
├── src/ ← código del SDK
│ ├── ArcaSdk.php ← Singleton y orquestador
│ ├── Asn1/
│ │ └── Asn1Builder.php
│ ├── Auditoria/
│ │ └── ResetAuditLogger.php
│ ├── Config/
│ │ └── Config.php
│ ├── Exceptions/
│ │ ├── ArcaException.php
│ │ ├── CaeSecuestradoException.php
│ │ ├── CbteRechazadoException.php
│ │ ├── ConfigException.php
│ │ ├── EmisionEnCursoException.php
│ │ ├── IdempotencyConflictException.php
│ │ ├── IdempotencyStateException.php
│ │ ├── MaxIdempotencyAttemptsException.php
│ │ ├── PadronArcaTransientException.php
│ │ ├── PadronException.php
│ │ ├── PadronProtocolException.php
│ │ ├── ValidationException.php
│ │ ├── WsaaCeeYaPoseeTaException.php
│ │ ├── WsaaException.php
│ │ ├── WsfeArcaTransientException.php
│ │ ├── WsfeException.php
│ │ ├── WsfeProtocolException.php
│ │ └── ZombieRecoveryFailedException.php
│ ├── Idempotencia/ ← persistencia y estados de emisión
│ │ ├── FilaEmision.php
│ │ ├── IdempotenciaRepository.php
│ │ └── UuidFactory.php
│ ├── Lock/
│ │ └── LockManager.php
│ ├── Padron/
│ │ ├── Actividad.php
│ │ ├── DomicilioFiscal.php
│ │ ├── Emisor.php
│ │ ├── Impuesto.php
│ │ ├── PadronClient.php
│ │ └── PadronSoapClientFactory.php
│ ├── Pdf/ ← generación local de comprobantes PDF con QR ARCA
│ │ ├── ComprobantePdfData.php ← detalle y totales validados
│ │ ├── ComprobantePdfGenerator.php
│ │ ├── ComprobantePdfMetadata.php
│ │ ├── ComprobantePdfTemplate.php ← plantilla A4 y paginación por copia
│ │ └── PdfDecimal.php ← validación y formato decimal
│ ├── Sdk/
│ │ └── Container.php
│ ├── Support/
│ │ ├── Money.php
│ │ ├── RetryPolicy.php
│ │ └── SoapTimeout.php
│ ├── Time/
│ │ └── Clock.php
│ ├── Wsaa/ ← autenticación y caché de tickets
│ │ ├── CmsSigner.php
│ │ ├── MysqlTicketCache.php
│ │ ├── NullTicketCache.php
│ │ ├── TicketCacheInterface.php
│ │ ├── TicketDeAcceso.php
│ │ ├── TraBuilder.php
│ │ └── WsaaClient.php
│ ├── Wsfe/ ← facturación electrónica
│ │ ├── Comprobante.php
│ │ ├── ComprobanteConsultado.php
│ │ ├── ComprobanteEmitido.php
│ │ ├── ComprobanteResponse.php
│ │ ├── DummyResponse.php
│ │ ├── IvaCalculator.php
│ │ ├── ResultadoIva.php
│ │ ├── SnapshotComparer.php
│ │ ├── SnapshotValidator.php
│ │ ├── SoapClientFactory.php
│ │ ├── TiposComprobante.php
│ │ └── WsfeClient.php
│ └── Zombie/ZombieRecovery.php ← recuperación de emisiones
├── tests/
│ ├── bootstrap.php
│ ├── run-mysql.sh
│ ├── Support/
│ │ └── TestEnvironment.php
│ └── unit/ ← suite existente; requisitos según módulo
│ ├── ArcaSdk/
│ │ ├── CapturingLogger.php
│ │ ├── ComprobantePdfGeneratorCapturing.php
│ │ ├── ComprobantePdfGeneratorPlantillaCapturing.php
│ │ ├── GenerarPdfPlantillaTest.php
│ │ ├── GenerarPdfTest.php
│ │ ├── ObtenerEmisorTest.php
│ │ ├── ReconciliacionTest.php
│ │ ├── ResetExternalIdTest.php
│ │ └── WsfeResponseBuilder.php
│ ├── ArcaSdkTest.php
│ ├── Asn1/
│ │ └── Asn1BuilderTest.php
│ ├── Config/
│ │ └── ConfigTest.php
│ ├── Idempotencia/
│ │ ├── FilaEmisionTest.php
│ │ ├── IdempotenciaRepositoryTest.php
│ │ └── UuidFactoryTest.php
│ ├── Lock/
│ │ ├── LockManagerDouble.php
│ │ └── LockManagerTest.php
│ ├── Padron/
│ │ ├── DomicilioFiscalTest.php
│ │ ├── EmisorTest.php
│ │ ├── PadronClientTest.php
│ │ ├── PadronSoapClientDouble.php
│ │ ├── PadronSoapClientFactoryTest.php
│ │ └── PadronWsaaClientDouble.php
│ ├── Pdf/
│ │ ├── ComprobantePdfGeneratorTest.php
│ │ └── ComprobantePdfMetadataTest.php
│ ├── ReviewRegressionTest.php
│ ├── Sdk/
│ │ ├── ContainerTest.php
│ │ └── PadronClientContainerTest.php
│ ├── smoke_config.php
│ ├── smoke_wsaa.php
│ ├── Support/
│ │ ├── MoneyTest.php
│ │ └── RetryPolicyTest.php
│ ├── Wsaa/
│ │ ├── CmsSignerDouble.php
│ │ ├── CmsSignerTest.php
│ │ ├── MysqlTicketCacheTest.php
│ │ ├── NullTicketCacheTest.php
│ │ ├── SoapClientDouble.php
│ │ ├── TicketDeAccesoTest.php
│ │ └── WsaaClientTest.php
│ ├── Wsfe/
│ │ ├── ComprobanteEmitidoTest.php
│ │ ├── ComprobanteResponseTest.php
│ │ ├── ComprobanteTest.php
│ │ ├── IvaCalculatorTest.php
│ │ ├── SnapshotComparerTest.php
│ │ ├── SnapshotValidatorTest.php
│ │ ├── SoapClientDouble.php
│ │ ├── TiposComprobanteTest.php
│ │ ├── WsaaClientDouble.php
│ │ └── WsfeClientTest.php
│ └── Zombie/
│ └── ZombieRecoveryTest.php
└── tools/
└── audit-docs.php
Costo de utilización
El SDK se distribuye bajo licencia MIT y su utilización es libre y gratuita, sin distinción entre el entorno de homologación y el entorno de producción. No se requiere el pago de licencia, canon ni suscripción por su empleo en ninguno de los dos entornos.
Atribución obligatoria
Toda aplicación que utilice el SDK debe incluir, en una sección accesible para el usuario final (por ejemplo, "Acerca de", "Créditos" o "Información legal"), una atribución visible al repositorio oficial del proyecto, con un enlace funcional a la fuente upstream en https://github.com/rbb-soft/ARCASdk.
Licencia
MIT. Texto legal completo en LICENSE (versión original en inglés) y LICENCIA.md (traducción de referencia al castellano, no oficial).