API REST - DTE360 | Documentación de la API

Introducción

La API REST de DTE360 te permite integrar facturación electrónica DTE directamente en tus sistemas. Todas las respuestas son en formato JSON y la autenticación se realiza mediante tokens Bearer (Laravel Sanctum).

Base URL

https://{tu-dominio}.dte360.com/api/v1

Autenticación

Bearer Token vía Laravel Sanctum

Formato

JSON en todas las respuestas

Rate Limiting

Límites según tu plan

Autenticación

Obtén un token de acceso mediante tus credenciales. Incluye el token en el encabezado Authorization de todas las solicitudes posteriores.

POST /api/v1/auth/login — Iniciar sesión y obtener token

Solicitud

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "usuario@empresa.com",
  "password": "tu-contraseña"
}

Respuesta — 200 OK

{
  "token": "1|abc123def456...",
  "user": {
    "id": 1,
    "name": "Juan Pérez",
    "email": "usuario@empresa.com"
  }
}

Incluye el token en todas las solicitudes:

Authorization: Bearer 1|abc123def456...

POST /api/v1/auth/logout — Revocar token actual

GET /api/v1/auth/me — Información del usuario actual

Facturas

Gestiona el ciclo completo de facturación electrónica: crea facturas, envíalas al Ministerio de Hacienda, descarga PDFs y realiza anulaciones.

GET /api/v1/invoices

Listar facturas con paginación. Filtrable por status, date_from, date_to, tipo_dte.

POST /api/v1/invoices

Crear una factura nueva.

Body (JSON)

{
  "tipo_dte": "01",       // 01=FC, 03=CCF, 14=FSE
  "customer_id": 15,
  "condicion_operacion": 1, // 1=Contado, 2=Crédito
  "items": [
    {
      "product_id": 1,
      "cantidad": 2,
      "precio_unitario": 25.00
    }
  ]
}

GET /api/v1/invoices/{id}

Obtener detalle de una factura específica.

POST /api/v1/invoices/{id}/submit

Enviar factura al Ministerio de Hacienda (MH) para su procesamiento DTE.

GET /api/v1/invoices/{id}/pdf

Descargar factura en formato PDF.

POST /api/v1/invoices/{id}/anular

Anular (invalidar) una factura previamente emitida.

Facturar (Todo en uno)

Crea y envía una factura al Ministerio de Hacienda en una sola llamada. Ideal para integraciones que requieren emisión inmediata del DTE.

POST /api/v1/invoices/facturar — Crear + enviar a MH automáticamente

Ejemplo completo

{
  "tipo_dte": "01",
  "receptor": {
    "tipo_documento": "36",
    "num_documento": "12345678901234",
    "nombre": "Cliente Ejemplo",
    "direccion": {
      "departamento": "06",
      "municipio": "14"
    }
  },
  "items": [
    {
      "cantidad": 2,
      "descripcion": "Producto ejemplo",
      "precio_unitario": 10.00,
      "tipo_item": 1
    }
  ],
  "condicion_operacion": 1,
  "forma_pago": "01"
}

Respuesta — 201 Created

{
  "invoice": {
    "id": 142,
    "codigo_generacion": "6BE1D284-B830-49E2-A280-C2C0D9164D7B",
    "numero_control": "DTE-01-S100P022-000000000000047",
    "sello_recibido": "2026031...",
    "estado_dte": "PROCESADO",
    "total": 22.60
  },
  "mh_response": {
    "estado": "PROCESADO",
    "selloRecibido": "2026031..."
  }
}

Clientes

Administra tu base de clientes. Cada cliente puede tener su NIT, DUI, dirección fiscal y datos de contacto para la emisión de DTE.

GET /api/v1/customers

Listar todos los clientes con paginación.

POST /api/v1/customers

Crear un cliente nuevo.

Body (JSON)

{
  "nombre": "Empresa Ejemplo S.A. de C.V.",
  "email": "contacto@empresa.com",
  "telefono": "2222-3333",
  "tipo_documento": "36",        // 36=NIT, 13=DUI
  "num_documento": "06141234567890",
  "nrc": "123456-7",
  "departamento": "06",
  "municipio": "14",
  "direccion": "Calle Principal #123, San Salvador"
}

GET /api/v1/customers/{id}

Obtener datos de un cliente específico.

PUT /api/v1/customers/{id}

Actualizar datos de un cliente.

Productos

Gestiona tu catálogo de productos y servicios. Cada producto incluye precio, costo, SKU, unidad de medida y tipo de impuesto para el cálculo automático de IVA.

GET /api/v1/products

Listar todos los productos con paginación.

POST /api/v1/products

Crear un producto nuevo.

Body (JSON)

{
  "nombre": "Servicio de Consultoría",
  "precio": 150.00,
  "costo": 0.00,
  "sku": "SRV-001",
  "unidad_medida": "99",         // Código DGII
  "tipo_item": 2,                // 1=Bien, 2=Servicio
  "gravado": true
}

GET /api/v1/products/{id}

Obtener datos de un producto específico.

PUT /api/v1/products/{id}

Actualizar datos de un producto.

Códigos de Estado

La API utiliza códigos de estado HTTP estándar para indicar el resultado de cada solicitud.

Código	Estado	Descripción
200	OK	Solicitud exitosa
201	Created	Recurso creado exitosamente
400	Bad Request	Errores de validación en los datos enviados
401	Unauthorized	Token inválido o no proporcionado
403	Forbidden	Tu plan no incluye acceso a la API
404	Not Found	Recurso no encontrado
422	Unprocessable Entity	Datos válidos pero no procesables
429	Too Many Requests	Límite de solicitudes excedido (rate limiting)
500	Internal Server Error	Error interno del servidor

Errores

Todas las respuestas de error siguen un formato consistente. Los errores de validación incluyen detalles por campo, y los errores del Ministerio de Hacienda incluyen información adicional.

Error de validación (422)

{
  "message": "Los datos proporcionados no son válidos.",
  "errors": {
    "tipo_dte": [
      "El campo tipo_dte es obligatorio."
    ],
    "items": [
      "Debe incluir al menos un ítem."
    ]
  }
}

Error del Ministerio de Hacienda

{
  "message": "Error al procesar DTE en MH.",
  "descripcionMsg": "RECHAZADO",
  "observaciones": [
    "El NIT del receptor no es válido."
  ]
}

Webhooks

Recibe notificaciones en tiempo real cuando ocurren eventos en tu cuenta. Los webhooks de pago permiten integrar pasarelas externas.

POST /api/webhooks/payment/{gateway}/{tenant}

Webhook de pago para pasarelas externas.

Wompi Stripe PayPal

Límites

Los límites de la API dependen de tu plan contratado. Si excedes el límite de solicitudes, recibirás un error 429 Too Many Requests.

Característica	Pro	Business
Solicitudes por minuto	60	300
Facturas por mes	5,000	Ilimitadas
Tokens activos	5	20
Webhooks
Soporte dedicado

Encabezados de rate limiting

Cada respuesta incluye los encabezados X-RateLimit-Limit, X-RateLimit-Remaining y Retry-After (cuando aplica).