API Facturación

Guia de Autenticación Rapida

Configura la autenticación con la API de Facturación Electrónica en pocos pasos.

Antes de comenzar

Necesitarás tener a mano tus credenciales del Ministerio de Hacienda y la información fiscal de tu empresa.

Paso 1: Registrar tu empresa

Primero debes registrar tu empresa y establecimientos usando el endpoint de registro:

POST /api/v1/auth/register

Registra tu empresa y establecimientos

Campos obligatorios

  • nit: NIT de la empresa (14 dígitos)
  • nrc: Número de registro fiscal (1-8 dígitos)
  • business_name: Razón social (1-150 caracteres)
  • economic_activity: Código de actividad económica según CAT-019
  • branch_offices: Al menos una sucursal tipo "02" (Casa matriz)

Ejemplo de Solicitud

Request 

{
  "nit": "12345678911227",
  "nrc": "1233260",
  "auth_type": "STANDARD",
  "phone": "21212828",
  "email": "facturacion@empresa.com.sv",
  "password_pri": "Tu-password-de-certificado#",
  "business_name": "EMPRESA DE PRUEBAS SA DE CV",
  "commercial_name": "EMPRESA DE PRUEBAS",
  "economic_activity": "47190",
  "economic_activity_desc": "Venta al por mayor de otros productos",
  "year_in_dte": true,
  "token_lifetime": 30,
  "branch_offices" : [
    {
      "establishment_type": "02",  // Casa matriz (obligatorio)
      "establishment_code": "C001",
      "address": {
        "department": "06",
        "municipality": "20",
        "complement": "BOULEVARD SANTA ELENA SUR, SANTA TECLA"
      }
    },
    {
      "establishment_type": "01",  // Sucursal adicional
      "establishment_code": "C002"
    }
  ]
}

Ejemplo de Respuesta

Response 

{
  "success": true,
  "data": [
    {
      "branch_number": 1,
      "establishment_type": "02",
      "establishment_code": "C001",
      "api_key": "b5fdbe3ed9d919ae0298...",  // ¡GUARDAR SEGURO!
      "api_secret": "4sIQwMA5CDc7wRIXU..."   // ¡GUARDAR SEGURO!
    },
    {
      "branch_number": 2,
      "establishment_type": "01",
      "establishment_code": "C002",
      "api_key": "4bceed47e1740e961...",
      "api_secret": "vOFgMVfnJLcjWqg5..."
    }
  ]
}

¡IMPORTANTE!

Guarda tu API key y API secret en un lugar seguro. No podrás recuperarlos después y tendrías que generar nuevas credenciales.

Paso 2: Obtener token JWT

Utiliza las credenciales recibidas para obtener un token JWT:

POST /api/v1/auth/login

Obtener un token JWT para autenticar solicitudes

Ejemplo de Solicitud

Request 

{
  "api_key": "b5fdbe3ed9d919ae0298...",
  "api_secret": "4sIQwMA5CDc7wRIXU...",
  "credentials": {
    "username": "TU-HACIENDA-USERNAME",
    "password": "TU-HACIENDA-PASSWORD-API"
  }
}

Ejemplo de Respuesta

Response 

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVC..."
  }
}

Paso 3: Usar el token para autenticarte

Incluye el token JWT en el encabezado de todas tus solicitudes posteriores:

GET /api/v1/dte/123456

Ejemplo de solicitud autenticada usando el token JWT

Incluye el siguiente encabezado en todas tus solicitudes: 

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVC...

Renovación del token

Para renovar el token antes de que expire, simplemente vuelve a realizar el paso 2. Se recomienda renovar el token unos días antes de su expiración para evitar interrupciones en el servicio.

Siguiente paso

¡Ya estás listo para comenzar a emitir documentos electrónicos!