arca-sdk

SDK en TypeScript para los web services de ARCA (Agencia de Recaudación y Control Aduanero, ex AFIP).

Estado: por ahora cubre sólo Consulta a Padrón (ws_sr_constancia_inscripcion). Otros servicios (facturación electrónica, etc.) van a ir sumándose en próximas versiones.

Instalación

pnpm add @inncode-io/arca-sdk
# (o npm i @inncode-io/arca-sdk / yarn add @inncode-io/arca-sdk)

Un solo paquete con todo: WsaaClient para autenticación, WsciClient para Consulta a Padrón, y los helpers de fechas/booleanos para parsear los strings que devuelve ARCA.

Uso rápido

Onboardear una empresa a partir de su CUIT — el caso de uso típico:

import { WsaaClient, WsciClient } from "@inncode-io/arca-sdk";

// Una sola vez al arrancar el backend.
const wsaa = new WsaaClient({
  env: "production",
  certPem: process.env.ARCA_WSAA_CERT_PEM!,   // desde tu secret manager
  keyPem: process.env.ARCA_WSAA_KEY_PEM!,
});

const wsci = new WsciClient({
  env: "production",
  credentialsProvider: wsaa,
  defaultCuitRepresentada: process.env.ARCA_CUIT_REPRESENTADA!,
});

// En cada onboarding:
const persona = await wsci.getPersona({ idPersona: cuitDelFormulario });

if (persona.errorConstancia) {
  throw new Error(`No se puede onboardear: ${persona.errorConstancia.error}`);
}

const dg = persona.datosGenerales!;
const nombreLegal = dg.tipoPersona === "JURIDICA"
  ? dg.razonSocial
  : `${dg.nombre} ${dg.apellido}`;

WsaaClient cachea el ticket de acceso por ~12 horas, así que con una sola instancia por proceso ya estás.

Cómo testearlo contra ARCA

• Producción (camino corto, para servicios de sólo lectura): ver scripts/PRODUCTION.md.
• Homologación (recomendado si vas a desarrollar features nuevas): ver scripts/HOMOLOGATION.md.

Ambas guías arrancan con un check de conectividad anónimo (dummy()) que no necesita credenciales y te confirma que el endpoint llega desde tu red.

Servicios cubiertos hoy

• ✅ ws_sr_constancia_inscripcion — Consulta a Padrón (constancia de inscripción de un contribuyente). Permite obtener datos generales, domicilio fiscal, régimen general, monotributo y caracterizaciones de cualquier CUIT, CUIL o CDI.

Servicios planificados

• ⏳ wsfev1 — Facturación electrónica.
• Otros web services de ARCA según demanda. Sugerencias y PRs bienvenidos.

Cómo está organizado el código

Aunque el SDK se distribuye como un solo paquete, internamente está dividido en tres módulos con responsabilidades distintas:

| Módulo | Para qué sirve | |---|---| | src/core/ | Transporte HTTP, helpers de XML, jerarquía de errores | | src/wsaa/ | Autenticación WSAA (firma del TRA con X.509 → token + sign) | | src/wsci/ | Cliente de ws_sr_constancia_inscripcion |

Todo se re-exporta desde el index.ts principal, así que un único import { ... } from "@inncode-io/arca-sdk" te alcanza para todo.

Requisitos

• Node.js ≥ 20
• pnpm ≥ 9 (sólo para desarrollar este repo; el paquete publicado se puede instalar con cualquier package manager)

Desarrollo

pnpm install
pnpm build
pnpm test

Licencia

MIT © inncode-io