Traducción de
docs/en/providers/contracts.md, que es el original. Si discrepan, manda el inglés.
La fidelidad al proveedor es el producto. Las rutas, las cabeceras exigidas, los campos de la petición, los estados, los errores y las firmas tienen que salir del contrato oficial o del SDK del proveedor, no de una forma interna cómoda.
#Precedencia de fuentes
Para un cambio de cara a un proveedor, consulta en este orden:
- La especificación oficial importada en
contracts/<proveedor>/y sudocs/en/fidelity/<proveedor>.md. - El SDK oficial cuando la especificación calla, o cuando lo que consume una integración es el comportamiento del SDK.
- El contrato de arquitectura de
.agents/. - La implementación y las pruebas actuales.
- La web, sólo para lo que no esté en lo anterior.
Si la implementación y el contrato oficial discrepan, el defecto es la implementación.
#Estado actual de los contratos
Hay instantáneas oficiales OpenAPI en contracts/mercadopago/mpOrders.json,
contracts/stripe/spec3.json y contracts/paypal/paypalOrders.json /
paypalPayments.json. Cada archivo tiene metadatos .meta.json con fuente,
fecha y SHA-256 de los bytes descargados. La validación del runtime sigue siendo
un subconjunto escrito a mano; no valida todo el OpenAPI.
Los límites de fidelidad y las rutas confirmadas están en:
#Importación explícita
El importador de Mercado Pago es opcional y con lista de permitidos:
ALLOW_CONTRACT_DOWNLOAD=true npm run contract:import:mercadopago --workspace @payment-emulator/api
Descarga el documento oficial configurado, canoniza el JSON y anota una suma SHA-256. Descargar contratos es herramienta, nunca parte del runtime de la API ni del worker. Verifica los artefactos generados y su atribución antes de versionarlos.
#Ampliar la cobertura de contrato
- Guarda el documento oficial y su suma en
contracts/<proveedor>/. - Anota origen, versión o fecha, y licencia o atribución.
- Deriva la validación del proveedor sin filtrar sus campos al modelo canónico.
- Añade casos de conformidad y comprobaciones con el SDK oficial donde se pueda.
- Di en el documento de fidelidad qué campos y productos no se soportan.
Una suma de comprobación demuestra qué documento se importó; no demuestra que el emulador implemente todas las operaciones de ese documento.
El importador opcional escribe instantáneas normalizadas en contracts/imported/,
que está ignorado por Git. Son distintas de las instantáneas de auditoría anteriores.