Cumplimiento / Integración SUNAT
Integración con las APIs de SUNAT: emitir y LEER (consultas)
Cómo nos integramos con SUNAT (emitir + leer su API)
Hay dos lados: emitir comprobantes y leer/consultar datos de SUNAT. ConTodo usa capas abstractas (pluggables por env) para ambos.
1. EMITIR comprobantes (CPE) — ya tenemos la capa
| Camino | Cómo | Veredicto |
|---|---|---|
| PSE/OSE (REST) | Un proveedor (Nubefact, Apisperú, Bizlinks…) genera el XML UBL 2.1, lo firma y lo envía a SUNAT; tú llamas su API REST | ✅ Recomendado (semanas) |
| SEE del contribuyente (directo) | Tú generas UBL 2.1, firmas con certificado digital y envías a los web services SOAP de SUNAT (sendBill, sendSummary) → recibes el CDR | Más control, más trabajo |
Implementado:
src/lib/sunat.ts(emitirComprobante) +POST /api/v1/comprobantes. Adaptador Nubefact + modo simulado si no hay proveedor. Cambiar de proveedor = cambiar el adaptador (no el resto).
2. LEER / consultar SUNAT (su API)
| Qué leer | API | Auth |
|---|---|---|
| Validar RUC / razón social / estado / condición | Consulta RUC oficial o proveedores (apis.net.pe, migo, factiliza) | Token del proveedor (simple) |
| Validez de comprobantes (CPE) | API REST "Consulta CPE / Validez" de SUNAT | OAuth2 SUNAT |
| Guías de remisión (GRE) | API REST GRE de SUNAT | OAuth2 SUNAT |
| SIRE (RVIE compras / RCE ventas) | API REST SIRE de SUNAT | OAuth2 SUNAT |
OAuth2 de SUNAT (para sus APIs REST)
- En Menú SOL → API creas credenciales (client_id + client_secret) ligadas a tu Clave SOL.
- Pides un token a
https://api-seguridad.sunat.gob.pe/v1/clientessol/{client_id}/oauth2/token(grantclient_credentialsopassword). - Llamas la API con
Authorization: Bearer <token>.
Ya implementado (lectura): validar RUC
src/lib/sunat.ts→consultarRuc(ruc)(pluggable porRUC_API_URL/RUC_API_TOKEN).GET /api/v1/sunat/ruc/:ruc(tenant por Bearer) → valida un RUC/DNI.- Uso en la app: al crear un cliente, autocompletar razón social y validar estado — y resolver el dolor del "cliente sin DNI" (ver [[22-ozas-implementacion]]).
3. Requisitos
- RUC + Clave SOL del cliente.
- Certificado digital tributario (solo para SEE directo).
- Credenciales OAuth2 (Menú SOL → API) para las APIs REST de SUNAT (CPE, GRE, SIRE).
- O un proveedor PSE/OSE + token (camino rápido).
4. Variables de entorno
# Emisión (PSE/OSE)
SUNAT_PROVIDER=nubefact
NUBEFACT_URL=...
NUBEFACT_TOKEN=...
# Lectura RUC (proveedor de consulta)
RUC_API_URL=https://api.apis.net.pe/v2/sunat/ruc?numero=
RUC_API_TOKEN=...
# APIs REST oficiales (OAuth2)
SUNAT_CLIENT_ID=...
SUNAT_CLIENT_SECRET=...
Recomendación: emitir vía PSE/OSE + leer RUC vía proveedor de consulta para arrancar rápido; sumar OAuth2 oficial para GRE/SIRE/validez cuando se necesite. Relacionado: [[23-integracion-sunat]] · [[32-api-integraciones]] · [[33-auth]].