Inicio Rápido

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.

1

Obtén tu API Key

Primero necesitas crear una cuenta y obtener tu API key para autenticarte.

Pasos para obtener tu API Key
Regístrate en el dashboard
Verifica tu email
Ve a "API Keys" y genera una nueva
Copia y guarda tu API key de forma segura
ℹ️

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.

2

Configura tu entorno

Instala las dependencias necesarias según tu lenguaje de programación.

terminal
npm install axios
# o con yarn
yarn add axios
3

Autentícate con la API

Configura tu cliente HTTP con tu API key para hacer llamadas autenticadas.

GET
/stats
Endpoint para verificar tu autenticación y ver tus estadísticas de uso
https://api.atto.sv/stats
auth.js
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();
4

Emite tu primera factura

Ahora vamos a emitir tu primera factura electrónica usando los datos mínimos requeridos.

POST
/factura/emitir
Crea y envía una factura electrónica al Ministerio de Hacienda
https://api.atto.sv/factura/emitir
primera-factura.js
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();
5

Verifica el resultado

Si todo salió bien, recibirás una respuesta como esta:

Respuesta exitosa
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