rckrdmrd
928eb795e6
- 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>
199 lines
4.5 KiB
Markdown
199 lines
4.5 KiB
Markdown
---
|
|
id: INT-004
|
|
type: Integration
|
|
title: "Mercado Pago"
|
|
provider: "MercadoPago"
|
|
status: Pendiente
|
|
integration_type: "payments"
|
|
created_at: 2026-01-04
|
|
updated_at: 2026-01-10
|
|
simco_version: "3.8.0"
|
|
tags:
|
|
- mercadopago
|
|
- payments
|
|
- point-of-sale
|
|
- multi-tenant
|
|
---
|
|
|
|
# INT-004: Mercado Pago
|
|
|
|
## Metadata
|
|
|
|
| Campo | Valor |
|
|
|-------|-------|
|
|
| **Codigo** | INT-004 |
|
|
| **Proveedor** | Mercado Libre |
|
|
| **Tipo** | Terminal de Pago |
|
|
| **Estado** | Pendiente |
|
|
| **Multi-tenant** | Si (por tenant) |
|
|
| **Fecha integracion** | - |
|
|
| **Ultimo update** | 2026-01-10 |
|
|
| **Owner** | Backend Team |
|
|
|
|
---
|
|
|
|
## 1. Descripcion
|
|
|
|
Mercado Pago es una opcion de terminal de pago fisica para que los duenos de tiendas puedan aceptar pagos con tarjeta. A diferencia de Stripe (que maneja suscripciones), MercadoPago se usa para cobros en punto de venta.
|
|
|
|
**Casos de uso principales:**
|
|
- Cobro con tarjeta en tienda fisica
|
|
- QR para cobro
|
|
- Generacion de links de pago
|
|
- Integracion con terminal Point
|
|
|
|
---
|
|
|
|
## 2. Credenciales Requeridas
|
|
|
|
### Variables de Entorno
|
|
|
|
| Variable | Descripcion | Tipo | Obligatorio |
|
|
|----------|-------------|------|-------------|
|
|
| `MERCADOPAGO_ACCESS_TOKEN` | Access Token de la aplicacion | string | SI |
|
|
| `MERCADOPAGO_PUBLIC_KEY` | Public Key para frontend | string | SI |
|
|
| `MERCADOPAGO_WEBHOOK_SECRET` | Secret para webhooks (IPN) | string | SI |
|
|
|
|
### Ejemplo de .env
|
|
|
|
```env
|
|
# Mercado Pago
|
|
MERCADOPAGO_ACCESS_TOKEN=APP_USR-xxxxxxxx
|
|
MERCADOPAGO_PUBLIC_KEY=APP_USR-xxxxxxxx
|
|
MERCADOPAGO_WEBHOOK_SECRET=xxxxxxxx
|
|
```
|
|
|
|
### Obtencion de Credenciales
|
|
|
|
1. Crear cuenta en [Mercado Pago Developers](https://www.mercadopago.com.mx/developers/)
|
|
2. Crear aplicacion
|
|
3. Obtener credenciales de produccion
|
|
4. Configurar URL de IPN (webhook)
|
|
|
|
---
|
|
|
|
## 3. Endpoints/SDK Utilizados
|
|
|
|
### Operaciones Planificadas
|
|
|
|
| Operacion | SDK Method | Descripcion |
|
|
|-----------|------------|-------------|
|
|
| Crear Preferencia | `preference.create()` | Link de pago |
|
|
| Crear QR | `qr.create()` | Cobro por QR |
|
|
| Consultar Pago | `payment.get()` | Estado del pago |
|
|
|
|
### SDK Planificado
|
|
|
|
```typescript
|
|
import { MercadoPagoConfig, Preference, Payment } from 'mercadopago';
|
|
|
|
const client = new MercadoPagoConfig({
|
|
accessToken: process.env.MERCADOPAGO_ACCESS_TOKEN,
|
|
});
|
|
|
|
const preference = new Preference(client);
|
|
|
|
// Crear link de pago
|
|
const result = await preference.create({
|
|
body: {
|
|
items: [{
|
|
title: 'Venta en tienda',
|
|
unit_price: 100,
|
|
quantity: 1,
|
|
}],
|
|
back_urls: {
|
|
success: 'https://michangarrito.com/pago/exitoso',
|
|
failure: 'https://michangarrito.com/pago/fallido',
|
|
},
|
|
},
|
|
});
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Rate Limits
|
|
|
|
| Limite | Valor | Periodo | Accion si excede |
|
|
|--------|-------|---------|------------------|
|
|
| API calls | 10,000 | por minuto | 429 |
|
|
|
|
---
|
|
|
|
## 5. Manejo de Errores
|
|
|
|
### Codigos de Error (Planeados)
|
|
|
|
| Codigo | Descripcion | Accion Recomendada |
|
|
|--------|-------------|-------------------|
|
|
| 400 | Parametros invalidos | Validar input |
|
|
| 401 | Token invalido | Verificar credenciales |
|
|
| 404 | Recurso no encontrado | Verificar ID |
|
|
|
|
---
|
|
|
|
## 6. Multi-tenant
|
|
|
|
### Modelo de Credenciales
|
|
|
|
- [x] **Por Tenant:** Cada tenant usa su cuenta MercadoPago
|
|
|
|
Los fondos van directo a la cuenta del dueno de la tienda.
|
|
|
|
### Almacenamiento Planificado
|
|
|
|
```sql
|
|
CREATE TABLE sales.tenant_mercadopago_config (
|
|
id UUID PRIMARY KEY,
|
|
tenant_id UUID REFERENCES auth.tenants(id),
|
|
access_token TEXT NOT NULL, -- Encriptado
|
|
public_key VARCHAR(100),
|
|
collector_id VARCHAR(50),
|
|
is_active BOOLEAN DEFAULT true,
|
|
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
|
|
UNIQUE(tenant_id)
|
|
);
|
|
```
|
|
|
|
---
|
|
|
|
## 7. Webhooks (IPN)
|
|
|
|
### Endpoints Planificados
|
|
|
|
| Evento | Endpoint Local | Descripcion |
|
|
|--------|----------------|-------------|
|
|
| `payment` | `/webhooks/mercadopago` | Pago recibido |
|
|
| `merchant_order` | `/webhooks/mercadopago` | Orden actualizada |
|
|
|
|
---
|
|
|
|
## 8. Estado de Implementacion
|
|
|
|
### Checklist
|
|
|
|
- [ ] Crear modulo MercadoPago en backend
|
|
- [ ] Implementar servicio de pagos
|
|
- [ ] Configurar webhooks
|
|
- [ ] Integrar con flujo de ventas
|
|
- [ ] Testing en sandbox
|
|
- [ ] Documentar flujo completo
|
|
|
|
### Bloqueadores
|
|
|
|
- Requiere onboarding de tenants a MercadoPago
|
|
- Proceso de verificacion de cuenta
|
|
|
|
---
|
|
|
|
## 9. Referencias
|
|
|
|
### Documentacion Oficial
|
|
- [MercadoPago Developers](https://www.mercadopago.com.mx/developers/es)
|
|
- [API Reference](https://www.mercadopago.com.mx/developers/es/reference)
|
|
- [SDK Node.js](https://github.com/mercadopago/sdk-nodejs)
|
|
|
|
---
|
|
|
|
**Ultima actualizacion:** 2026-01-10
|
|
**Estado:** PENDIENTE DE IMPLEMENTACION
|