rckrdmrd 928eb795e6 [SIMCO-V38] feat: Actualizar a SIMCO v3.8.0 + cambios apps

- HERENCIA-SIMCO.md actualizado con directivas v3.7 y v3.8
- Cambios en backend y frontend

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-10 08:53:05 -06:00

6.3 KiB

Raw Permalink Blame History

type

title

provider

status

integration_type

created_at

updated_at

simco_version

INT-006: Pagos CoDi/SPEI

Metadata

Campo	Valor
Codigo	INT-006
Proveedor	Banxico/STP
Tipo	Pagos QR instantáneos
Estado	Mock (en desarrollo)
Multi-tenant	Si
Fecha planeada	2026-Q1
Owner	Backend Team

1. Descripcion

Integración con el sistema de Cobro Digital (CoDi) de Banxico y transferencias SPEI a través de STP (Sistema de Transferencias y Pagos). Permite a los changarros recibir pagos instantáneos mediante códigos QR, sin comisiones por transacción. CoDi opera sobre la infraestructura de SPEI, garantizando transferencias en tiempo real 24/7.

Casos de uso principales:

Generación de códigos QR para cobro instantáneo
Recepción de pagos SPEI sin comisión
Notificación en tiempo real de pagos recibidos
Conciliación automática de transacciones
Generación de comprobantes electrónicos de pago

2. Credenciales Requeridas

Variables de Entorno

Variable	Descripcion	Tipo	Obligatorio
STP_EMPRESA	Identificador de empresa en STP	string	SI
STP_CLAVE_PRIVADA	Llave privada para firmar mensajes	string	SI
STP_CERTIFICADO	Certificado digital .cer	string	SI
STP_CUENTA_CLABE	CLABE de la cuenta receptora	string	SI
STP_WEBHOOK_URL	URL para recibir notificaciones	string	SI
CODI_MERCHANT_ID	ID de comercio registrado en CoDi	string	SI
CODI_API_KEY	Llave de API de CoDi	string	SI

Ejemplo de .env

# Pagos CoDi/SPEI
STP_EMPRESA=MICHANGARRITO
STP_CLAVE_PRIVADA=/path/to/private_key.pem
STP_CERTIFICADO=/path/to/certificate.cer
STP_CUENTA_CLABE=646180157000000001
STP_WEBHOOK_URL=https://api.michangarrito.mx/webhooks/stp
CODI_MERCHANT_ID=codi_mer_xxxxxxxx
CODI_API_KEY=codi_key_xxxxxxxx

3. Arquitectura

┌─────────────────────────────────────────────────────────────────┐
│                      MiChangarrito                              │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────────┐  │
│  │   Frontend   │───▶│  API Server  │───▶│  CoDiService     │  │
│  │   (POS/App)  │    │              │    │                  │  │
│  └──────────────┘    └──────────────┘    └────────┬─────────┘  │
└────────────────────────────────────────────────────┼────────────┘
                                                     │
                           ┌─────────────────────────┼─────────────┐
                           │                         ▼             │
                           │  ┌──────────────────────────────┐    │
                           │  │         STP Gateway          │    │
                           │  └──────────────┬───────────────┘    │
                           │                 │                     │
                           │                 ▼                     │
                           │  ┌──────────────────────────────┐    │
                           │  │     Banxico SPEI / CoDi      │    │
                           │  │   (Red Interbancaria MX)     │    │
                           │  └──────────────────────────────┘    │
                           │           Sistema Financiero         │
                           └───────────────────────────────────────┘

Flujo de Pago CoDi

Comercio genera solicitud de cobro con monto
Sistema genera código QR con datos CoDi
Cliente escanea QR con app bancaria
Banco del cliente procesa transferencia SPEI
STP notifica la recepción del pago
Sistema actualiza estado de la venta en tiempo real

4. Endpoints

Endpoints Consumidos (STP/CoDi API)

Método	Endpoint	Descripción
POST	`/v1/codi/cobros`	Generar solicitud de cobro CoDi
GET	`/v1/codi/cobros/{id}`	Consultar estado de cobro
POST	`/v1/spei/ordenPago`	Registrar orden de pago SPEI
GET	`/v1/spei/consultaOrden/{id}`	Consultar orden SPEI
GET	`/v1/cuentas/{clabe}/movimientos`	Consultar movimientos

Endpoints Expuestos (MiChangarrito)

Método	Endpoint	Descripción
POST	`/api/v1/payments/codi/generate`	Generar QR de cobro
GET	`/api/v1/payments/codi/{id}/status`	Consultar estado
GET	`/api/v1/payments/codi/{id}/qr`	Obtener imagen QR
POST	`/api/v1/webhooks/stp`	Recibir notificaciones STP
GET	`/api/v1/payments/spei/movements`	Listar movimientos

5. Notas de Implementacion

CoDi no cobra comisiones por transacción (beneficio vs tarjetas)
Las transferencias SPEI son irreversibles una vez confirmadas
Implementar timeout de 5 minutos para códigos QR
Validar firma digital en todas las notificaciones de STP
El registro como participante CoDi requiere trámite con Banxico
Generar referencia única por transacción para conciliación
Los QR deben cumplir con el estándar EMVCo para CoDi
Horario de operación SPEI: 24/7, pero cortes contables a las 17:30
Considerar implementar caché de CLABEs validadas
Manejar reintentos en caso de falla de comunicación con STP

6.3 KiB Raw Permalink Blame History