Fidelidad del emulador de Mercado Pago

Índice / Index · English

Original: docs/en/fidelity/mercadopago.md. Revisión del 2026-09-06 usando los dos índices de llms/mercado-pago. El OpenAPI oficial y su checksum están en contracts/mercadopago/; la validación sigue siendo un subconjunto manual.

#Fuentes

Las referencias oficiales de creación, procesamiento, captura, devolución, estados y Checkout Pro.

#Superficie

Método	Ruta	Operación
POST	`/v1/orders`	crear
GET	`/v1/orders/{id}`	consultar
POST	`/v1/orders/{id}/transactions`	agregar una transacción
POST	`/v1/orders/{id}/process`	procesar
POST	`/v1/orders/{id}/capture`	capturar
POST	`/v1/orders/{id}/cancel`	cancelar
POST	`/v1/orders/{id}/refund`	devolver

Base: http://localhost:8080/mercadopago, con prefijo opcional y autenticación Bearer. Cada POST requiere X-Idempotency-Key de 1–128 caracteres; UUID v4 es una recomendación. processing_mode: manual crea una orden vacía; se agrega una transacción con POST /v1/orders/{id}/transactions (HTTP 201) antes de /process. Se rechazan procesar sin transacción y agregar una segunda. Los IDs usan ORD. capture_mode: manual autoriza y espera /capture. Son independientes. La captura es total, con cuerpo vacío. La devolución parcial utiliza transactions: [{ id: "<id del pago devuelto por la API>", amount: "10.00" }]; {} devuelve lo que queda capturado. El antiguo amount en la raíz se rechaza.

#Estados

Canónico	status	status_detail
created	created	created
requires_action	action_required	waiting_payment
authorized	action_required	waiting_capture
captured / settled	processed	accredited
devolución parcial	processed	partially_refunded
canceled	canceled	canceled
failed	failed	failed
refunded	refunded	refunded
disputed	charged_back	in_process

Los escenarios pueden sobrescribir el vocabulario. Los de pendiente y rechazo incluidos usan ahora los estados de Orders, sin mezclar los de Payments.

#Qué se emula

Creación, consulta, procesamiento, autorización, captura total, cancelación y reembolso total/parcial de una transacción sintética. IDs estables, importes por reembolso y fechas created_date/last_updated_date, sin devolver tokens de tarjeta. Idempotencia, locks, contabilidad, outbox y notificaciones firmadas compartidos. Mapeo de moneda para MLA, MLB, MLM, MLC, MCO, MPE y MLU.

El checkout utiliza azul y blanco, medios de pago apilados, resumen del comercio e inicio opcional para saldo interno. Pix solo aparece para BRL y Pago Fácil para ARS. Los controles de simulación son secundarios.

El checkout respeta la captura manual: autoriza sin cobrar; la API captura después.

#Qué no se emula

OpenAPI completo: validación parcial de campos, métodos, totales y errores.
El SDK oficial mercadopago@3.6.0 no permite cambiar el host mediante su configuración pública. Se verifica su validador de firmas, no sus peticiones.
Tokenización, QR/Pix, cupones, cuotas ni procesamiento asíncrono real. Un escenario y la confirmación local determinan el resultado.
Preferences y Checkout Pro. La URL local es una capacidad del plano de control, no un init_point; el kit es una aproximación, no el SDK ni una réplica capturada.
Múltiples transacciones, modificación/eliminación de la transacción agregada, pagos divididos y marketplace. Se permite agregar una a una orden manual vacía.
Fidelidad completa de devoluciones: conversión según el sitio configurado, sin usar currency_id sintético para devoluciones entre monedas; sin colección de historial independiente. Las devoluciones ya responden HTTP 201.
Errores completos de Orders: varios errores internos conservan el formato antiguo error/message/status/cause.
Tarifas reales. 2,9 % + 0,30, reserva de siete días y disputa sin comisión son parámetros sintéticos configurables, no precios regionales verificados.