Esta guía condensa lo que explicamos en cada onboarding técnico del Plan API: cómo pasar de cero a tu primera factura electrónica aprobada desde tu propio sistema, y los errores que vemos repetirse en las integraciones. Si venís evaluando conectarte directo al SIFEN versus usar un proveedor, empezá por acá: GOEKUA recibe un JSON, genera el XML, lo firma, lo transmite al SIFEN con reintentos automáticos y te devuelve el estado** vos no tocás XML ni certificados en tu código.
Lo que necesitás antes de la primera llamada
- Empresa habilitada como facturador electrónico: certificado de firma digital (archivo .p12 con contraseña) y timbrado electrónico. Se gestionan desde la plataforma — guía del certificado acá.
- Plan API activo (desde Gs. 110.000/mes por hasta 200 llamadas; al superar el volumen el plan escala automáticamente).
- Un usuario responsable: cada documento se emite en nombre de un usuario, que es el responsable ante el SIFEN. Recomendación: creá un usuario dedicado para la integración (ej. `facturacion@tuempresa`), no uses el personal del dueño.
Staging y producción: dos ambientes, dos claves.
Tenés un ambiente de staging idéntico a producción para desarrollar sin emitir documentos reales. Tres cosas que confunden a todos al principio:
- La URL base es distinta (la de pruebas incluye `staging`) y cada ambiente tiene su propia API key — verificá siempre contra qué ambiente estás tirando.
- El certificado de firma es el mismo en ambos ambientes… pero el timbrado es distinto por ambiente (el de pruebas lo emite el SIFEN de test).
- Todo lo que emitas por API también se ve en el panel web útil para que el equipo administrativo verifique mientras desarrollás.
El flujo es asíncrono (y eso cambia tu diseño)
El SIFEN no responde en tiempo real: enviás el documento, queda "en revisión", y la aprobación llega después (típicamente minutos; más en horas pico los cierres contables entre el 25 y el 5 de cada mes saturan al ente). Tu integración debe:
- Enviar el documento (JSON con cliente, tipo de operación, ítems).
- Consultar el estado por CDC hasta obtener aprobado/rechazado.
- Manejar el rechazo como un estado normal del flujo, no una excepción: corregir y reenviar.
GOEKUA amortigua la intermitencia del SIFEN con colas y reintentos automáticos — si el ente se cae, tus documentos se retransmiten solos cuando vuelve.
Los 4 errores que vemos en todas las integraciones
1. Duplicados por timeout. Si tu sistema reintenta un envío que dio timeout, podés emitir dos veces la misma factura. La solución es la idempotencia: generá el CDC antes de enviar — si reintentás con el mismo CDC, el documento es el mismo. Es el consejo técnico más valioso de esta guía.
2. Rechazos por dígito verificador. Que un RUC "exista" no alcanza: la consulta con dígito verificador (DV) confirma que es un contribuyente activo. Bases de datos con DV desactualizados son la causa #1 de rechazos masivos en integraciones. Usá el endpoint de consulta de RUC (autocompleta la razón social) antes de emitir.
3. Notas de crédito sobre innominadas. No se puede emitir una NC sobre una factura innominada: primero se nomina el documento (se le asigna receptor) y después va la NC. La API soporta el evento de nominación.
4. Enviar todo a fin de mes en hora pico. Si tu operación lo permite, programá los lotes fuera de las horas de saturación — la fecha retroactiva te deja emitir en horario tranquilo manteniendo la fecha efectiva del documento.
¿Qué cuenta como "llamada"?
Los documentos emitidos y recibidos cuentan para el cupo del plan (una factura de compra que ingresa por el RPA de Marangatú también es una llamada). Las consultas de estado no agotan tu plan de la misma forma — el detalle está en la documentación de la API.
Checklist del primer sprint
- [ ] Cuenta creada, certificado y timbrado gestionados
- [ ] API key de staging obtenida; primera factura de prueba emitida y aprobada
- [ ] Consulta de estado por CDC implementada (con polling razonable)
- [ ] CDC generado antes del envío (idempotencia)
- [ ] Validación de RUC + DV integrada al alta de clientes
- [ ] Manejo de rechazo → corrección → reenvío
- [ ] Cambio a producción: nueva API key + timbrado de producción
¿Integrando un ecommerce? Mirá el webinar Ventajas de integrar facturación electrónica a tu ecommerce. ¿Un ERP existente? Los tiempos reales de integración van de 2 semanas a 6 meses según el sistema. El soporte técnico acompaña con videollamadas la puesta a punto del JSON — escribinos por WhatsApp o empezá por la documentación.