Logo

Documentación de API

Integra tu sistema con nuestra API de Facturación Electrónica

Base URL: https://miventa.pe/api

Introducción

Nuestra API REST te permite integrar la emisión de comprobantes electrónicos (boletas, facturas, notas de crédito/débito) directamente en tu sistema.

Características principales:
  • Autenticación mediante API Keys (recomendado para integraciones)
  • Emisión de comprobantes electrónicos conforme a SUNAT
  • Cliente flexible (creación automática de clientes)
  • Descarga de PDF y XML firmados
  • Consultas por serie y número

Autenticación

La API utiliza API Keys para autenticación. Cada usuario puede crear múltiples API Keys para diferentes propósitos (desarrollo, producción, etc.).

¿Cómo obtener una API Key?

Las API Keys se generan exclusivamente desde el Dashboard Web. Inicia sesión en tu cuenta y ve a la sección "Configuración" → "API Keys" para crear y gestionar tus claves.

Importante: Las API Keys solo se muestran una vez al crearlas. Guárdalas de forma segura.

Obtener API Key

Para obtener una API Key, debes crearla desde el Dashboard Web de tu cuenta.

Pasos para obtener tu API Key:
  1. Inicia sesión en tu cuenta en el dashboard web
  2. Navega a "Configuración" → "API Keys"
  3. Haz clic en "Crear API Key"
  4. Completa el formulario:
    • Nombre: Un nombre descriptivo (ej: "API Key Producción")
    • Fecha de expiración: (Opcional) Fecha límite de validez
    • IP Whitelist: (Opcional) IPs permitidas separadas por coma
  5. ⚠️ Copia y guarda la API Key que se muestra (solo se muestra una vez)
Características de las API Keys:
  • Formato: sk_ seguido de 48 caracteres aleatorios
  • Puedes crear múltiples API Keys para diferentes propósitos
  • Puedes configurar restricción por IP para mayor seguridad
  • Puedes establecer fecha de expiración opcional
  • Puedes revocar API Keys en cualquier momento desde el dashboard

Usar API Key

Puedes usar tu API Key de dos formas:

1. Header Authorization (Recomendado)

HTTP Header 
Authorization: Bearer sk_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz

2. Header X-API-Key

HTTP Header 
X-API-Key: sk_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz

Endpoints de Comprobantes

Los siguientes endpoints aceptan autenticación mediante API Keys. Usa tu API Key en el header Authorization: Bearer {tu_api_key}.

Consultar Comprobante

GET https://miventa.pe/api/comprobantes

Lista todos los comprobantes con filtros opcionales.

Query Parameters:
Parámetro Tipo Requerido Descripción
empresa_id integer No Filtrar por empresa
estado string No Filtrar por estado (pendiente, aceptado, rechazado, anulado)
fecha_desde date No Fecha desde (YYYY-MM-DD)
fecha_hasta date No Fecha hasta (YYYY-MM-DD)
GET https://miventa.pe/api/comprobantes/numero/{serie-numero}

Consulta un comprobante por su serie y número (ej: B001-00000001).

Emitir Comprobante

POST https://miventa.pe/api/comprobantes

Crea un nuevo comprobante electrónico. El cliente puede enviarse por ID o crearse automáticamente.

Body Parameters:
Parámetro Tipo Requerido Descripción
tipo_comprobante_id integer Sí ID del tipo de comprobante (1=Factura, 2=Boleta, etc.)
cliente object Sí* Datos del cliente (si no se envía cliente_id)
cliente.tipo_documento_id integer Sí* ID del tipo de documento (2=DNI, 4=RUC)
cliente.numero_documento string Sí* Número de documento del cliente
cliente.razon_social string Sí* Razón social o nombre del cliente
detalles array Sí Array de productos/servicios
detalles[].cantidad number Sí Cantidad del producto
detalles[].precio_unitario number Sí Precio unitario (sin IGV si igv_incluido=true)
igv_incluido boolean No Si el IGV está incluido en el precio (default: false)
JSON 
{
  "tipo_comprobante_id": 2,
  "cliente": {
    "tipo_documento_id": 2,
    "numero_documento": "12345678",
    "razon_social": "Juan Pérez García"
  },
  "detalles": [
    {
      "descripcion": "Producto Test",
      "cantidad": 2,
      "precio_unitario": 10.00,
      "tipo_igv": "10"
    }
  ],
  "igv_incluido": true
}

Descargar PDF/XML

GET https://miventa.pe/api/comprobantes/{id}/pdf

Descarga el PDF del comprobante.

GET https://miventa.pe/api/comprobantes/{id}/xml

Descarga el XML firmado del comprobante.

Ejemplos de Código

cURL

Bash 
# Emitir boleta
curl -X POST "https://miventa.pe/api/comprobantes" \
  -H "Authorization: Bearer sk_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo_comprobante_id": 2,
    "cliente": {
      "tipo_documento_id": 2,
      "numero_documento": "12345678",
      "razon_social": "Juan Pérez"
    },
    "detalles": [
      {
        "descripcion": "Producto Test",
        "cantidad": 1,
        "precio_unitario": 10.00
      }
    ],
    "igv_incluido": true
  }'

JavaScript (Fetch API)

JavaScript 
const apiKey = 'sk_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz';
const baseUrl = 'https://miventa.pe/api';

// Emitir boleta
async function emitirBoleta() {
  const response = await fetch(`${baseUrl}/comprobantes`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      tipo_comprobante_id: 2,
      cliente: {
        tipo_documento_id: 2,
        numero_documento: '12345678',
        razon_social: 'Juan Pérez'
      },
      detalles: [
        {
          descripcion: 'Producto Test',
          cantidad: 1,
          precio_unitario: 10.00
        }
      ],
      igv_incluido: true
    })
  });

  const data = await response.json();
  console.log(data);
}

PHP (Guzzle)

PHP 
<?php
use GuzzleHttp\Client;

$apiKey = 'sk_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz';
$baseUrl = 'https://miventa.pe/api';

$client = new Client([
    'base_uri' => $baseUrl,
    'headers' => [
        'Authorization' => "Bearer {$apiKey}",
        'Content-Type' => 'application/json'
    ]
]);

// Emitir boleta
$response = $client->post('/comprobantes', [
    'json' => [
        'tipo_comprobante_id' => 2,
        'cliente' => [
            'tipo_documento_id' => 2,
            'numero_documento' => '12345678',
            'razon_social' => 'Juan Pérez'
        ],
        'detalles' => [
            [
                'descripcion' => 'Producto Test',
                'cantidad' => 1,
                'precio_unitario' => 10.00
            ]
        ],
        'igv_incluido' => true
    ]
]);

$data = json_decode($response->getBody(), true);
print_r($data);
?>

Python (Requests)

Python 
import requests

api_key = 'sk_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz'
base_url = 'https://miventa.pe/api'

headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

# Emitir boleta
data = {
    'tipo_comprobante_id': 2,
    'cliente': {
        'tipo_documento_id': 2,
        'numero_documento': '12345678',
        'razon_social': 'Juan Pérez'
    },
    'detalles': [
        {
            'descripcion': 'Producto Test',
            'cantidad': 1,
            'precio_unitario': 10.00
        }
    ],
    'igv_incluido': True
}

response = requests.post(f'{base_url}/comprobantes', json=data, headers=headers)
print(response.json())

Códigos de Error

Código Descripción Solución
401 No autenticado Verifica que tu API Key sea correcta y esté activa
403 IP no autorizada Tu IP no está en la whitelist de la API Key
403 Sin permisos Tu usuario no tiene permisos para esta acción
422 Error de validación Revisa los datos enviados en el request
500 Error del servidor Contacta al soporte técnico

Mejores Prácticas

Seguridad
  • Gestiona tus API Keys desde el Dashboard Web (Configuración → API Keys)
  • Nunca compartas tu API Key en código público o repositorios
  • Usa restricción de IP cuando sea posible (configurable desde el dashboard)
  • Rota tus API Keys periódicamente
  • Usa diferentes API Keys para desarrollo y producción
  • Configura fecha de expiración para API Keys temporales
  • Revoca API Keys que ya no uses (desde el dashboard)
Desarrollo
  • Guarda la API Key en variables de entorno
  • Implementa manejo de errores adecuado
  • Usa HTTPS en producción
  • Implementa rate limiting en tu aplicación
  • Valida los datos antes de enviarlos