Primeros pasos con Atto
Aprende a emitir tu primera factura electrónica en menos de 10 minutos. Esta guía te llevará desde la configuración inicial hasta tu primera transacción exitosa.
Obtén tu API Key
Primero necesitas crear una cuenta y obtener tu API key para autenticarte.
Consejo: Tu API key comienza con sk_user_ o sk_admin_ dependiendo de tu rol. Cada API key está asociada a un emisor, sucursal y ambiente (PRUEBAS o PRODUCCIÓN). Nunca compartas tu API key en repositorios públicos.
Configura tu entorno
Instala las dependencias necesarias según tu lenguaje de programación.
npm install axios
# o con yarn
yarn add axiosAutentícate con la API
Configura tu cliente HTTP con tu API key para hacer llamadas autenticadas.
1const axios = require('axios');
2
3const apiKey = 'sk_user_tu_hash_de_64_caracteres_aqui';
4const baseURL = 'http://localhost:3000'; // o tu dominio en producción
5
6const api = axios.create({
7 baseURL,
8 headers: {
9 'Content-Type': 'application/json',
10 'X-API-Key': apiKey
11 }
12});
13
14// Verificar conexión
15async function verificarConexion() {
16 try {
17 const response = await api.get('/stats');
18 console.log('✅ Conexión exitosa:', response.data);
19 } catch (error) {
20 console.error('❌ Error de conexión:', error.response?.data);
21 }
22}
23
24verificarConexion();Emite tu primera factura
Ahora vamos a emitir tu primera factura electrónica usando los datos mínimos requeridos.
1// Tu primera factura electrónica
2async function emitirPrimeraFactura() {
3 const facturaData = {
4 // NO incluir folio, tipoMoneda, ni ambiente
5 // Estos se generan automáticamente por la API
6 items: [
7 {
8 cantidad: 1,
9 descripcion: "Consultoría en desarrollo web",
10 precioUni: 150.00,
11 // Campos opcionales:
12 tipoItem: 2, // 2 = Servicio
13 codigo: "SERV001",
14 uniMedida: 99, // 99 = Otros
15 montoDescu: 0
16 }
17 ],
18 pagos: [
19 {
20 codigo: "01", // 01 = Efectivo
21 montoPago: 150.00,
22 // Campos opcionales:
23 referencia: "Pago completo al contado"
24 }
25 ],
26 receptor: {
27 tipoDocumento: "36", // 36 = NIT
28 numDocumento: "0614-010190-103-1",
29 nombre: "Empresa Cliente S.A. de C.V.",
30 // Campos opcionales: nrc, correo, telefono, direccion
31 }
32 };
33
34 try {
35 const response = await api.post('/factura/emitir', facturaData);
36
37 console.log('🎉 ¡Factura creada exitosamente!');
38 console.log('Código de generación:', response.data.codigoGeneracion);
39 console.log('Número de control:', response.data.numeroControl);
40 console.log('Estado:', response.data.estado);
41 console.log('Sello recibido:', response.data.selloRecibido);
42
43 return response.data;
44 } catch (error) {
45 console.error('❌ Error al emitir factura:', error.response?.data);
46 throw error;
47 }
48}
49
50// Ejecutar
51emitirPrimeraFactura();Verifica el resultado
Si todo salió bien, recibirás una respuesta como esta:
1{
2 "estado": "PROCESADO",
3 "tipoDte": "Factura Electrónica",
4 "selloRecibido": "MINISTERIO DE HACIENDA - SELLO DIGITAL",
5 "numeroControl": "DTE-01-0001-00000001",
6 "codigoGeneracion": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890",
7 "fecEmi": "2025-01-16",
8 "horEmi": "10:30:00",
9 "fhProcesamiento": "2025-01-16T10:30:05.000Z",
10 "clasificaMsg": null,
11 "codigoMsg": "001",
12 "descripcionMsg": "Procesado correctamente",
13 "observaciones": [],
14 "dteJson": {
15 "identificacion": { ... },
16 "emisor": { ... },
17 "receptor": { ... }
18 },
19 "dteFirmado": "eyJhbGciOiJSUzUxMiJ9..."
20}¡Felicidades! Has emitido tu primera factura electrónica. El documento fue validado, firmado digitalmente y enviado al Ministerio de Hacienda exitosamente.
Requisitos Previos Importantes
📋 Antes de poder emitir DTEs, necesitas:
- Configurar al menos un Emisor con NIT, NRC y datos completos
- Subir el Certificado Digital X.509 (.p12) del emisor
- Configurar al menos una Sucursal para el emisor
- Generar una API Key asociada al emisor y sucursal
🔐 Sobre los Certificados:
- Los certificados se obtienen del Ministerio de Hacienda
- Formato requerido:
.p12(PKCS#12) - Necesitas la contraseña del certificado para subirlo
- Los certificados se almacenan de forma segura en Cloudflare R2
🌍 Ambientes Disponibles:
- PRUEBAS: Para desarrollo y testing (apitest.dtes.mh.gob.sv)
- PRODUCCION: Para emisión real con validez fiscal (api.dtes.mh.gob.sv)
- Cada API key está asociada a un ambiente específico