API MEYPAR Colombia - Docucenter
Saltar a contenido

🅿️ API MEYPAR Colombia - Facturación Electrónica

📋 Descripción

API completa para integración con el sistema MEYPAR Colombia, especializada en facturación electrónica para estacionamientos y servicios de parqueo. Incluye dos modalidades de procesamiento: asíncrona y con emisión directa.

Integración Completa

Esta API proporciona sincronización completa con MEYPAR Colombia, incluyendo terminales, productos de estacionamiento, recargas eléctricas y servicios premium con emisión automática de facturación electrónica.

📋 Endpoints Disponibles

🚀 1. Crear Venta MEYPAR (Asíncrona)

Endpoint: POST /api/v1/fe/create_sale_meypar
Controller: FeController::createSaleMeypar
Request Class: CreateSaleMeyparRequest
Procesamiento: Asíncrono usando CreateSaleMeyparJob

📋 Descripción

Crea y emite una factura electrónica basada en datos del sistema MEYPAR Colombia. El procesamiento se realiza de forma asíncrona mediante jobs en cola.

🔐 Autenticación

Authorization: Bearer {token}
Content-Type: application/json

📥 Respuesta de Éxito (Test)

{
  "response": "HTTP: 201 OK",
  "success": true,
  "message": "Factura Meypar procesada exitosamente",
  "job_id": "uuid-generated-job-id"
}

⚡ 2. Crear Venta MEYPAR con Emisión Directa

Endpoint: POST /api/v1/fe/create_sale_meypar_with_emission
Controller: FeController::createSaleMeyparWithEmission
Request Class: CreateSaleMeyparRequest
Procesamiento: Síncrono con emisión automática

📋 Descripción

Crea y procesa una factura electrónica con emisión directa basada en datos del sistema MEYPAR Colombia. Este endpoint procesa la venta de manera síncrona incluyendo la emisión automática mediante el PAC configurado, con sistema de reintentos integrado.

🔄 Diferencias Principales

Característica create_sale_meypar create_sale_meypar_with_emission
Procesamiento Asíncrono (Job) Síncrono con emisión directa
Emisión FE Separada Automática integrada
Respuesta Job despachado Resultado completo
Reintentos Manual Automático con MeyparService
Tiempo respuesta Inmediato Variable (depende de PAC)

📥 Respuesta de Éxito - Emisión Directa

{
  "success": true,
  "message": "Venta MEYPAR creada y emitida exitosamente",
  "attempt": 1,
  "data": {
    "sale": {
      "id": 12345,
      "invoice_number": "MEYPAR-EMISSION-001",
      "customer_name": "María Elena Rodríguez",
      "total": "8000.0000",
      "invoice_date": "2025-08-12",
      "issued": true
    },
    "emission": {
      "success": true,
      "cufe": "FE012000155702081-2-2021-2600002025081179999999990010127999999993",
      "transition_id": "01K2G9PGACC8BDC4NYP5D5HMZE",
      "numeroDocumentoFiscal": "0000001234",
      "pac_response": {
        "sale": 12345,
        "path": "invoices",
        "transition": "01K2G9PGACC8BDC4NYP5D5HMZE",
        "cufe": "FE012000155702081-2-2021-2600002025081179999999990010127999999993",
        "codigoSucursalEmisor": "001",
        "numeroDocumentoFiscal": "0000001234",
        "puntoFacturacionFiscal": "001",
        "tipoDocumento": "01",
        "tipoEmision": "01",
        "signedXml": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4..."
      }
    }
  }
}

❌ Respuesta de Error - Después de 3 Reintentos

{
  "success": false,
  "message": "Falló después de 3 intentos",
  "error": "Error procesando venta MEYPAR con emisión"
}

📊 Estructura del Request

La estructura del request es idéntica para ambos endpoints. Basado en la documentación MEYPAR Colombia y los objetos WADetalleFactura, WAMedioPagoFactura, WATerminalID:

📦 Ejemplo Completo de Request

{
  "documento": {
    "tipo_documento": "1",
    "numero": "MEYPAR-INTEGRATION-001",
    "fecha": "2025-08-12",
    "emisor": {
      "nombre": "Estacionamientos MEYPAR Colombia SAS",
      "nit": "900123456-1",
      "direccion": "Calle 123 #45-67, Bogotá D.C.",
      "telefono": "+57 1 2345678",
      "email": "emisor@meypar.co"
    },
    "adquiriente": {
      "nombre": "Carlos Eduardo Morales",
      "nit": "79123456-7",
      "email": "carlos.morales@gmail.com",
      "direccion": "Carrera 15 #32-18, Bogotá D.C.",
      "telefono": "+57 310 5678901"
    },
    "terminal": {
      "CodigoTerminal": 7,
      "CodigoExterno": "TERM-BOG-001",
      "NombreTerminal": "Terminal Centro Comercial Unicentro"
    },
    "items": [
      {
        "objectName": "WADetalleFactura",
        "cantidad": 1,
        "descripcion": "Cobro Estancia Vehiculo - 2 horas 30 min",
        "precioUnitario": 4500.00,
        "codigoProducto": "EST-VEHICULO",
        "codigoVehiculo": 1,
        "unidadMedida": "UNI",
        "precioTotalSinDescuento": 4500.00,
        "precioTotalFinalDetalle": 4500.00,
        "observacion": "150min - Entrada: 14:30, Salida: 17:00"
      },
      {
        "objectName": "WADetalleFactura",
        "cantidad": 1,
        "descripcion": "Recarga Electrica Vehiculo",
        "precioUnitario": 8000.00,
        "codigoProducto": "RECARGA-ELECT",
        "codigoVehiculo": 1,
        "unidadMedida": "KWH",
        "precioTotalSinDescuento": 8000.00,
        "precioTotalFinalDetalle": 8000.00,
        "observacion": "15 KWH - Tiempo: 45min"
      }
    ],
    "medios_pago": [
      {
        "objectName": "WAMedioPagoFactura",
        "codigoMedioPago": 2,
        "importeMedioPago": 12500.00
      }
    ],
    "totales": {
      "total": 12500.00,
      "subtotal": 12500.00,
      "impuestos": 0.00,
      "descuentos": 0.00,
      "moneda": "COP"
    },
    "autorizacion_prefijo": {
      "objectName": "WAAutorizacionPrefijo",
      "PrefijoId": "UNI1",
      "ResolucionNumero": "18764000000123",
      "VigenciaFecha": "2026-12-31",
      "VigenciaDuracion": 24,
      "CorrelativoInicialNum": 1,
      "CorrelativoFinalNum": 50000
    }
  }
}

💡 Casos de Uso

🅿️ Estacionamientos

  • Cobro de estancia: Facturación por tiempo de permanencia
  • Zonas VIP: Estacionamiento premium con servicios adicionales
  • Estacionamiento nocturno: Tarifas especiales por horario

⚡ Servicios Eléctricos

  • Recarga de vehículos eléctricos: Por KWH consumidos
  • Servicios de carga rápida: Tarifas premium

🔧 Servicios Adicionales

  • Lavado de vehículos: Servicios de limpieza
  • Servicios premium: Atención personalizada
  • Multi-terminal: Soporte para múltiples terminales

⚙️ Configuraciones Requeridas

📋 PAC Connection

  • Configuración PAC activa en la organización
  • Token válido y endpoint configurado
  • Certificados digitales válidos

🔧 MeyparService

  • Servicio configurado para la organización
  • Mapeo de productos MEYPAR a códigos internos
  • Configuración de impuestos y tarifas

📊 Monitoreo y Mejores Prácticas

📈 Consideraciones de Performance

Aspecto Impacto Recomendación
Tiempo de respuesta Variable (PAC + procesamiento) Implementar timeout en cliente
Reintentos automáticos Hasta 3 intentos con sleep(1-3s) Mostrar indicador de progreso
Conexión PAC Dependiente del proveedor PAC Monitorear disponibilidad
Procesamiento de datos Creación de registros BD Optimizar queries de inserción

✅ Validaciones Específicas

  • Items: Mínimo 1 item requerido
  • Medios de Pago: Al menos un medio de pago
  • Terminal: Validación opcional pero recomendada
  • Moneda: Soporte para COP, USD, PAB
  • Fecha: Formato YYYY-MM-DD

🔍 Mejores Prácticas

  1. Timeout del cliente: Configurar timeout mínimo de 30 segundos
  2. Manejo de errores: Implementar fallback a método asíncrono si falla
  3. Cache de resultados: Evitar reprocesamiento (verificar EzeeIssued)
  4. Monitoring: Alertas por alta latencia o errores frecuentes
  5. Validación previa: Verificar configuración PAC antes del envío
  6. XML firmado: Para Alanube, el XML base64 se incluye en signedXml

📞 Soporte

Para soporte con integración MEYPAR:

  • Email: desarrollo@apconpanama.me
  • GitHub: Reportar Issues
  • Documentación: Índice de APIs
  • MEYPAR Colombia: Soporte técnico especializado en integración