miinventario-v2/docs/02-integraciones/INT-003-7eleven.md

# INT-003: Integracion 7-Eleven

---
id: INT-003
type: Integration
status: Pendiente
version: "1.0.0"
created_date: 2026-01-10
updated_date: 2026-01-10
simco_version: "4.0.0"
---

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | INT-003 |
| **Servicio** | Agregador de pagos (Conekta/OpenPay) |
| **Proposito** | Pagos en efectivo en tiendas 7-Eleven |
| **Criticidad** | P1 |
| **Estado** | Pendiente |

---

## 1. Descripcion

Integracion con un agregador de pagos mexicano para permitir pagos en efectivo en tiendas 7-Eleven.

---

## 2. Opciones de Agregador

| Agregador | Soporte 7-Eleven | Costo | Documentacion |
|-----------|------------------|-------|---------------|
| **Conekta** | Si | ~3.9% | https://developers.conekta.com |
| **OpenPay** | Si | ~3.5% | https://www.openpay.mx/docs |
| **PayU** | Parcial | ~4% | https://developers.payulatam.com |

**Recomendacion:** Conekta por mejor soporte en Mexico.

---

## 3. Configuracion (Conekta)

### Variables de Entorno

```env
CONEKTA_API_KEY=key_...
CONEKTA_WEBHOOK_SECRET=whsec_...
SEVEN_ELEVEN_EXPIRATION_HOURS=48
```

### Instalacion

```bash
npm install conekta
```

---

## 4. Flujo de Integracion

```
┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│  Mobile  │───▶│ Backend  │───▶│ Conekta  │───▶│7-Eleven  │
└──────────┘    └──────────┘    └──────────┘    └──────────┘
     │               │               │               │
     │ 1. Request    │               │               │
     │   7-11 pay    │               │               │
     │──────────────▶│               │               │
     │               │ 2. Create     │               │
     │               │   cash order  │               │
     │               │──────────────▶│               │
     │               │◀──────────────│               │
     │◀──────────────│  Reference    │               │
     │               │               │               │
     │ 3. User pays  │               │               │
     │   at 7-11     │───────────────────────────────▶
     │               │               │◀──────────────│
     │               │ 4. Webhook    │               │
     │               │◀──────────────│               │
     │◀──────────────│ 5. Notify     │               │
```

---

## 5. Implementacion Backend

### Crear Referencia 7-Eleven

```typescript
import Conekta from 'conekta';

@Injectable()
export class ConektaService {
  constructor() {
    Conekta.api_key = process.env.CONEKTA_API_KEY;
    Conekta.api_version = '2.0.0';
  }

  async create7ElevenPayment(
    amount: number,
    email: string,
    name: string,
    orderId: string
  ) {
    const expiresAt = Math.floor(
      Date.now() / 1000 + parseInt(process.env.SEVEN_ELEVEN_EXPIRATION_HOURS) * 3600
    );

    const order = await Conekta.Order.create({
      currency: 'MXN',
      customer_info: {
        name,
        email,
      },
      line_items: [{
        name: 'Creditos MiInventario',
        unit_price: Math.round(amount * 100),
        quantity: 1,
      }],
      charges: [{
        payment_method: {
          type: 'cash',
          expires_at: expiresAt,
        },
      }],
      metadata: {
        orderId,
      },
    });

    const cashCharge = order.charges.data[0];
    const paymentMethod = cashCharge.payment_method;

    return {
      conektaOrderId: order.id,
      reference: paymentMethod.reference,
      barcodeUrl: paymentMethod.barcode_url,
      expiresAt: new Date(expiresAt * 1000),
    };
  }
}
```

### Webhook Handler

```typescript
@Post('webhook/conekta')
async handleConektaWebhook(
  @Body() body: any,
  @Headers('digest') digest: string
) {
  // Verificar firma
  const isValid = this.verifyConektaSignature(body, digest);
  if (!isValid) {
    throw new UnauthorizedException('Invalid signature');
  }

  if (body.type === 'order.paid') {
    const orderId = body.data.object.metadata.orderId;
    await this.handlePaymentComplete(orderId);
  }

  return { received: true };
}
```

---

## 6. Estructura de Referencia

| Campo | Descripcion |
|-------|-------------|
| reference | Numero de referencia para pagar |
| barcode_url | URL de imagen del codigo de barras |
| expires_at | Timestamp de expiracion |

---

## 7. Consideraciones

| Aspecto | Valor |
|---------|-------|
| Monto minimo | $10 MXN |
| Monto maximo | $10,000 MXN |
| Expiracion | 48 horas recomendado |
| Tiempo confirmacion | 5-15 minutos |
| Comision | ~3.9% + IVA |

---

## 8. Diferencias vs OXXO

| Aspecto | OXXO (Stripe) | 7-Eleven (Conekta) |
|---------|---------------|-------------------|
| Proveedor | Stripe | Conekta |
| Cobertura | 20,000+ tiendas | 2,000+ tiendas |
| Comision | ~3.6% | ~3.9% |
| Integracion | Mas simple | Requiere agregador |

---

## 9. Testing

### Modo Sandbox

```typescript
// Usar API key de sandbox
CONEKTA_API_KEY=key_test_...
```

### Simular Pago

En el dashboard de Conekta sandbox, se puede simular el pago de una referencia.

---

## 10. Referencias

- [Conekta Docs](https://developers.conekta.com)
- [MII-013](../01-epicas/MII-013-pagos-7eleven.md)
- [ADR-0004](../97-adr/ADR-0004-pagos-efectivo-mexico.md)

---

**Ultima Actualizacion:** 2026-01-10