> ## Documentation Index > Fetch the complete documentation index at: https://docs.cotizave.com/llms.txt > Use this file to discover all available pages before exploring further. # Buenas prácticas de integración > Recomendaciones para integrar tasas, conversiones, histórico y webhooks de Cotizave en producción. Esta guía reúne decisiones de integración para V2. Si mantienes una integración V1, consulta la [guía de migración](https://docs.cotizave.com/api/v2/migration.md) antes de cambiar sus rutas o respuestas. ## Mantén la API key en tu servidor Envía `X-API-Key` solo desde tu backend. No pongas una key en JavaScript del navegador, una aplicación distribuida, una URL ni logs. Expón a tu interfaz un endpoint propio con los campos que realmente necesita. ## Descubre la tasa antes de usarla No derives un identificador desde un nombre ni sustituyas una tasa porque comparta moneda con otra. Consulta `GET /v2/fx/{CC}/rates`, conserva el `id` recibido y úsalo para detalle, histórico o conversión cuando el endpoint lo acepte. Una tasa registrada puede no tener una observación actual. Consulta la [cobertura de datos e histórico](https://docs.cotizave.com/api/coverage.md) y la [matriz V2 por plan](https://docs.cotizave.com/api/v2/rates-by-plan.md) antes de depender de un mercado. ## Cachea con un límite de antigüedad explícito Evita llamar a Cotizave una vez por cada visitante. Comparte una caché en tu backend y define cuánto tiempo acepta tu producto mostrar un dato anterior. En V2, conserva el `ETag` y usa `If-None-Match` para una lectura condicional; sus respuestas son privadas y varían por API key, así que no compartas una respuesta autenticada entre cuentas. La caché no reemplaza la validación de frescura. Revisa `updated_at` y, cuando el endpoint y el plan los incluyan, `effective_date`, `stale`, `staleness_sec` y `stale_after_sec`. ## Conserva el contexto de cada cálculo Al guardar una conversión, precio o importe facturado, conserva el ID o mercado aplicado, monedas, importe, `updated_at` y, cuando existan, fecha valor y campos de frescura. La API calcula con la tasa publicada: no incluye comisiones ni garantiza la ejecución de una operación. Para una referencia que tenga fecha valor, no sustituyas `effective_date` por `updated_at`. Una observación actualizada durante un día no hábil puede seguir teniendo una fecha valor anterior. ## Consulta histórico sin inventar días Pro permite consultar hasta 365 días hacia atrás; los demás planes tienen una ventana menor. Puedes pedir un rango de un año cuando tu plan lo permita, pero el resultado no garantiza 365 puntos: una serie puede no publicar fines de semana, feriados u otros días. Usa el mismo ID que recibiste de la colección. No rellenes automáticamente las fechas ausentes ni supongas que el histórico de una tasa representa otra. Un `403 history_out_of_retention` indica que el rango excede tu plan; `404 history_not_available` indica que esa serie no expone histórico y `404 rate_not_found` puede indicar que no hubo observación para la fecha. Consulta [cobertura](https://docs.cotizave.com/api/coverage.md) e [histórico V2](https://docs.cotizave.com/api/v2/history.md). ## Maneja errores por código, no por texto No reintentes sin cambios los errores de entrada, credenciales o plan: `400`, `401`, `402`, `403` y los `404` de un recurso ausente requieren corregir la causa. Para un fallo transitorio de lectura, limita los reintentos, usa espera creciente y define un plazo total. Ante `429`, respeta `Retry-After` y revisa las cabeceras de cuota disponibles. Distingue el agotamiento mensual de un límite de solicitudes por minuto: repetir una petición no resuelve el primero. No repitas automáticamente un `POST` si no sabes si el servidor lo procesó. Lee [errores](https://docs.cotizave.com/api/errors.md) y [cuotas y límites](https://docs.cotizave.com/api/rate-limits.md) para los códigos y cabeceras. ## Trata el uso como consumo compartido V1 y V2 comparten la cuota mensual de la cuenta. Cuenta también los reintentos, trabajos en segundo plano y procesos paralelos. Un sondeo frecuente por proceso puede agotar la cuota aunque cada petición individual sea válida. ## Procesa webhooks de forma idempotente Si usas webhooks, verifica su firma, persiste el evento de forma idempotente y responde `2xx` solo después de guardarlo de manera duradera. Un `2xx` confirma la entrega; no lo envíes antes de que tu sistema pueda procesar el evento. Consulta [webhooks](https://docs.cotizave.com/guides/webhooks.md) para firma, reintentos y pausas. ## Prueba los casos que cambian el resultado Antes de desplegar, prueba al menos una tasa restringida por plan, una fecha fuera de retención, una fecha sin observación, una respuesta marcada como `stale`, un `429` y un fallo transitorio de red. Verifica también que una clave inválida nunca llegue al navegador ni quede registrada en logs. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.