DOCSEARCHbyAlgolia
Submit Docs

Arca SDK

repository·main·Indexed 40 days ago

https://github.com/ralcorta/arcasdk

A TypeScript library for consuming ARCA (formerly AFIP) Web Services. It provides tools for electronic billing (WSFE), managing tax records, and generating official electronic voucher PDFs via the @arcasdk/core and @arcasdk/pdf packages. Version 0.1.0.

Tokens
60.1K
Snippets
169
Records
277
Agent score
49%

What's inside Arca SDK

  1. Overview of Arca SDK services

    main

    The SDK provides type-safe wrappers for various ARCA web services:

    • Facturación Electrónica: Emission and authorization of vouchers (CAE) for invoices A, B, C, credit notes, etc.
    • Facturación de Exportación: WSFEX service for export voucher authorization and queries.
    • Factura de Crédito (MiPyMEs): WSFECred service for acceptance, rejection, and current accounts.
    • Comprobantes T (Turismo): WSCT service for authorizing class T vouchers for foreign tourists.
    • Consulta de Padrón: Real-time validation of CUITs and fiscal data.
    • Constancia de Inscripción: Programmatic verification of registration certificates.
    • Servicio Genérico: Ability to make SOAP calls to any ARCA WSDL, even without a dedicated wrapper.

  2. Overview of available ARCA services

    main

    The Arca SDK provides typed support for various ARCA web services, including:

    • Autenticación (WSAA): Automatic management of access tickets.
    • Facturación Electrónica (WSFE): Issuing electronic invoices.
    • Padrón (Alcance 4, 5, 10, 13): Querying taxpayer data, exempt entities, Monotributo, and economic activities.
    • Constancia de inscripción: Certificate of registration.
    • Facturación de exportación (WSFEX): Export invoices.
    • Factura de crédito MiPyMEs (WSFECred): SME electronic credit invoices.
    • Comprobantes T de turismo (WSCT): Tourism accommodation vouchers.
    • Servicio genérico: Ability to interact with any ARCA WSDL.
    • PDF de comprobantes: A generator for receipts using ARCA-compliant designs.

  4. Use advanced Use Cases for custom wiring

    main

    For advanced composition, every service method has a corresponding Use Case exported from @arcasdk/core. These can be instantiated manually by providing the appropriate repository port (e.g., I*RepositoryPort).

    Examples of exported Use Cases:

    • Authentication: LoginUseCase, RequestLoginUseCase, GetAuthParamsUseCase.
    • Electronic Billing: CreateVoucherUseCase, GetCaeaUseCase, GetSalesPointsUseCase.
    • Register: GetTaxpayerDetailsUseCase, GetRegisterServerStatusUseCase.
    • WSFEX: AuthorizeUseCase, GetCmpUseCase.
    • WSFECRED: AceptarFECredUseCase, ConsultarComprobantesUseCase.

  5. How the Arca API is structured

    main

    The main Arca class instance acts as a gateway to all available services. It exposes:

    • Typed Services: Methods like electronicBillingService, wsfexService, wsfecredService, wsctService, and various padrones services.
    • Constants: ArcaServiceNames for identifying services.
    • Ticket Storages: For managing authentication state.
    • DTOs: Data Transfer Objects exported from the package for type-safe interactions.

  6. Use automatic calculations and overrides in InvoiceData

    main

    The PDF generator performs certain calculations automatically, but you can provide overrides in your InvoiceData object to use specific values.

    CalculationAutomatic FormulaOverride Field
    Item Discount ($)precioUnitario × cantidad × (bonificacion / 100)item.importeBonificacion
    Total in ARS (Foreign Currency)importeTotal × cotizacionimporteTotalPesos

    If an override field is provided, the generator uses that value directly without recalculating.

  7. Access services via the Arca class

    main

    All service methods are accessed through the Arca instance using the pattern arca.<serviceProperty>.<method>(...).

    Input and output types for these methods are exported from @arcasdk/core (for example, IVoucher or IFEXAuthorizeInput).

    // Pattern: arca.<service>.<method>(params)
await arca.electronicBillingService.createVoucher(voucherData);

  8. Use the genericService for custom SOAP calls

    main

    If a specific ARCA service is not yet exposed as a dedicated property on the Arca class, or if you need to test a service using a custom WSDL, use genericService.call().

    When using FE_DUMMY or other services without a bundled WSDL, you must provide the wsdlContent in the options object.

    // Example of calling a service via the generic interface
await arca.genericService.call(
  ArcaServiceNames.WSSR_PADRON_FOUR,
  "dummy",
  { /* options */ },
);

  9. Understand layout differences by Invoice Letter (A, B, C, E, M)

    main

    The PDF generator adjusts the layout based on the cbteLetra provided in InvoiceData:

    • Factura A: 7 columns (includes %IVA). Includes a fixed 5-row 'Other Taxes' table and VAT breakdown by rate (27%, 21%, etc.). Includes 'Son PESOS ARGENTINOS...' legend.
    • Factura B: 6 columns (no %IVA). Includes a fixed 5-row 'Other Taxes' table. Shows Subtotal + Other Taxes + Total. Includes 'Son PESOS ARGENTINOS...' legend.
    • Factura C: 6 columns (no %IVA). No 'Other Taxes' table. Shows Net Taxable + Total. Includes 'Son PESOS ARGENTINOS...' legend.
    • Factura E (Exportation): 5 columns (Item, Description, Qty, Unit Price USD, Total USD). Features specific receiver sections (Country CUIT, Tax ID, Currency, Destination). Includes a table for Payment Method, Payment Date, and Incoterms. Footer shows Exchange Rate and Currency.
    • Factura M: Uses the same layout as Factura B (6 columns, no VAT breakdown).

  10. How SOAP engines and runtimes are selected

    main

    The SDK automatically detects the execution environment to select the appropriate SOAP transport engine:

    • Node.js: Uses the HttpClient from the soap package.
    • Universal: Uses fetch for environments like Cloudflare Workers, browsers, and other non-Node environments.

    Detection is handled internally via detectSoapRuntime, and the engine is instantiated using createSoapEngine.

  11. Implement custom token storage with ITicketStoragePort

    main

    For serverless environments or when you want to centralize tokens in Redis, PostgreSQL, or S3 without passing credentials manually in every request, implement the ITicketStoragePort interface.

    When using ticketStorage, the SDK automatically handles token renewal through your adapter. This is more efficient than manual management because you don't need to pass credentials to every new Arca() instance.

    import {
  Arca,
  MemoryTicketStorage,
  FileSystemTicketStorage,
  type ITicketStoragePort,
} from "@arcasdk/core";

// Use MemoryTicketStorage for short-lived processes (e.g., tests)
const ticketStorage: ITicketStoragePort = new MemoryTicketStorage({
  cuit: 20111111112,
  production: false,
});

// Use FileSystemTicketStorage with a controlled path
const ticketStorageFs = new FileSystemTicketStorage({
  ticketPath: "/tmp/arca-tickets",
  cuit: 20111111112,
  production: false,
});

const arca = new Arca({
  cuit: 20111111112,
  cert: "...",
  key: "...",
  ticketStorage: ticketStorageFs,
});

  12. Understand WSAA Authentication and Token Lifecycles

    main

    To interact with ARCA web services, you must authenticate via the WSAA service. The resulting tokens are valid for 12 hours.

    Important Rate Limits:

    • Production: 1 request every 2 minutes.
    • Homologation (Testing): 1 request every 10 minutes.

    Best Practice: Do not request a new token for every API call. Generate a token once and reuse it for its 12-hour validity period to avoid hitting rate limits.