¡Bienvenido al emocionante viaje con Cobre, la plataforma de movimiento de dinero disponible en diversas geografías!Cobre Platform ofrece productos de pago a través de APIs. Estos productos son accesibles mediante endpoints sencillos, proporcionando a los clientes funcionalidades de pago sin complicaciones. Cobre maneja todas las complejidades del procesamiento de pagos, liberando a los clientes de las complejidades de las operaciones de movimiento de dinero.¡Conéctate con nuestro equipo de Desarrollo de Negocios hoy para desbloquear tu acceso a Cobre Platform. Estamos ansiosos por conectar contigo y comenzar este extraordinario viaje juntos!Seguridad de la API#
En Cobre, priorizamos hacer que la seguridad sea sencilla y accesible. Obtener y usar nuestras claves de API está diseñado para ser directo, asegurando que puedas integrar y operar de forma segura con nuestra plataforma desde el inicio. Cada solicitud de API debe realizarse a través del robusto protocolo HTTPS. Este compromiso no solo establece un entorno seguro para todas tus transacciones, sino que también protege sin esfuerzo contra las vulnerabilidades de las solicitudes HTTP obsoletas. Con Cobre, experimentas la cúspide de la seguridad con la máxima facilidad.Cobre recomienda encarecidamente considerar las siguientes medidas de seguridad al integrar nuestras APIs:
• Almacenar las credenciales API en un lugar seguro - por ejemplo, un vault (e.g., Hashicorp Vault, CyberArk, AWS Secrets Manager)
• Rotar los secretos API con frecuencia (Recomendación - una vez al mes)
• Configurar API Whitelisting en ambas partes (Cliente y Cobre)IPs de Cobre: 50.17.12.196, 54.173.144.191
Para configurar las IPs del Cliente, se debe enviar un ticket a soporte@cobre.co
• Configurar Secure Key para Webhooks
• Separar los ambientes de Dev/Test y de Production para segregar el acceso - Cobre ofrece ambientes independientes para facilitar esta separación. Fechas y Fechas/Horas (UTC): Dominando las Zonas Horarias#
Cobre utiliza la zona horaria universal UTC para todos los campos de fecha y fecha/hora dentro de nuestra plataforma, ofreciendo una experiencia unificada del tiempo. Este enfoque asegura que independientemente de dónde estén ubicados nuestros clientes, el tiempo de las transacciones y operaciones se mantenga consistente y sincronizado.Ejemplos#
Timestamp UTC: "2023-07-15T12:00:00Z"En Colombia (UTC-5), este timestamp se traduce al 15 de julio de 2023, a las 7:00 AM.
En Ciudad de México (UTC-6 durante Horario Estándar), esto representa el 15 de julio de 2023, a las 6:00 AM.
Timestamp UTC: "2023-11-10T18:30:00Z"En Colombia (UTC-5), esto corresponde al 10 de noviembre de 2023, a la 1:30 PM.
En Ciudad de México (UTC-6 durante Horario Estándar), esto significa el 10 de noviembre de 2023, a las 12:30 PM o 1:30 PM dependiendo del horario de verano.
Detalles de Paginación#
Comprender la estructura de nuestras respuestas de API es clave para navegar y utilizar Cobre Platform de manera efectiva. Aquí tienes un desglose de nuestro sistema de paginación:total_items (number): El número total de elementos devueltos por la API.
total_pages (number): El número de páginas dado el tamaño de página actual.
is_last_page (boolean): Un indicador verdadero/falso que muestra si la página actual es la última página. Por defecto: false.
page_items (number): El número de elementos en la página actual. Por defecto: 50.
page_size (number): Puedes establecer el número máximo de elementos en una página.
page_number (number): Puedes seleccionar la página.
contents (array): Un arreglo que contiene los elementos de la página actual.
Ten en cuenta que no es posible paginar más de 10,000 registros.
Pautas de Rendimiento: Consideraciones sobre Límites de Tasa y Ráfaga#
Límite de Tasa (Rate-limiting)#
La API pública de Cobre soporta 30 transacciones por segundo (TPS) en operación en estado estable. Para garantizar un rendimiento consistente y evitar errores HTTP 429 (Too Many Requests), recomendamos seguir estas buenas prácticas de uso de la API:Implementar retroceso exponencial con lógica de reintentos.
Usar llaves de idempotencia en todas las operaciones sensibles.
Evitar patrones de sondeo agresivo.
Optimizar la frecuencia de solicitudes y el procesamiento por lotes cuando aplique.
Apoyarse en Webhooks para actualizaciones asíncronas siempre que sea posible.
Límite de Ráfaga (Burst-limit)#
Además del límite de tasa sostenida, la llave de API de cada cliente tiene un límite de ráfaga de 200 solicitudes, implementado mediante un algoritmo de cubo de tokens. Este cubo almacena hasta 200 tokens (uno por solicitud) y se recarga a una tasa de 30 tokens por segundo, equivalente al límite de tasa en estado estable.La capacidad de 200 solicitudes es un búfer de uso único, no un límite repetible por segundo. Una vez consumida, solo se recarga a 30 tokens/segundo, por lo que el tráfico sostenido por encima de 30 TPS agotará el cubo y eventualmente generará respuestas HTTP 429.
Por ejemplo: si se envían 100 solicitudes en el primer segundo con el cubo lleno, las 100 se procesan exitosamente y el cubo se recarga en 30 (quedando en 130/200). Sin embargo, si se sostienen 50 solicitudes/segundo de forma continua, el búfer de 200 tokens se agota en cuestión de segundos, tras lo cual las solicitudes excedentes se limitan a la tasa de recarga de 30 TPS hasta que el volumen de solicitudes se normalice.
Importante: Dado que todas las credenciales bajo un mismo cliente comparten una única llave de API subyacente, crear múltiples credenciales (por ejemplo, para distintos servicios o casos de uso) no incrementa el rendimiento disponible.
Distribuir las solicitudes uniformemente — escalone las solicitudes de manera regular en el tiempo en lugar de enviarlas en grandes lotes.
Implementar un algoritmo de cubo de tokens o cubo con fuga en su propio sistema — estos patrones absorben naturalmente las ráfagas respetando los límites de tasa.
Monitorear proactivamente las respuestas 429 — trátelas como una señal para reducir el ritmo de inmediato y reintentar con retroceso exponencial.
Evitar reintentos sincronizados — si múltiples procesos reintentam simultáneamente tras una falla, se puede amplificar la ráfaga. Agregue variación aleatoria (jitter) a los intervalos de reintento.
Convenciones de la API#
Idempotencia#
Las solicitudes POST para transferencias de dinero y transferencias cross border requieren un encabezado idempotency para evitar operaciones duplicadas al reintentar la operación. Si se recibe la misma clave nuevamente, Cobre devuelve la respuesta original sin volver a ejecutar la operación.| Regla | Detalle |
|---|
| Requerido en | /v1/money_movements, /v1/cross_border_money_movements |
| Método | POST |
| Longitud mínima | 9 caracteres |
| Encabezado faltante | Devuelve HTTP 400 |
Montos#
Todas las cantidades monetarias () en la API de Cobre se expresan en la unidad monetaria más pequeña de la moneda (unidades menores).| Moneda | Unidad más pequeña | Cantidad | Valor de la API |
|---|
| COP | centavos | $1.500,20 COP | 150020 |
| MXN | centavos | $2.390,15 MXN | 239015 |
| USD | centavos | $1.52 USD | 152 |
Esto se aplica de forma consistente a todos los endpoints: movimientos de dinero, balances, transacciones y cotizaciones de divisas. 