Todo lo que tu ERP, tu CRM o tu core necesitan para operar sin entrar al portal: consultar cuentas y clientes, darlos de alta, seguir cada entrada, barrer saldo y originar salidas. Las decisiones que requieren una persona —aprobar, resolver excepciones, configurar— se siguen tomando en el portal.
Creá la credencial
En API y webhooks, elegí sobre qué empresas opera y qué puede hacer. La llave se muestra una sola vez.
Probá en el ambiente de pruebas
Una empresa aparte con datos que no son reales. Las credenciales de pruebas solo la ven a ella.
Registrá la dirección de avisos
Para enterarte al instante de cada entrada, salida o cambio de cuenta, sin consultar en bucle.
Tu primera llamada
curl "https://conectademo.monetae.io/api/public/v1/accounts?limit=5" \ -H "Authorization: Bearer <tu llave>"
Autenticación
Mandá la llave en Authorization: Bearer …. Cada llamada queda registrada a nombre de esa integración.
Empresa
Toda operación ocurre dentro de una empresa. Enviá company_id cuando la credencial abarca más de una; si abarca una sola, se asume.
Repetir sin duplicar
En las creaciones mandá Idempotency-Key: repetir la llamada con la misma llave devuelve el resultado original. En salidas y barridos es obligatoria.
Listados
Paginación por cursor: pedí limit y seguí con el next_cursor de la respuesta.
Montos y fechas
Los montos viajan como decimal en texto con su moneda; las fechas en ISO 8601 en UTC.
Identificadores
Cada recurso tiene su identificador propio. El número de cuenta virtual no es el identificador de la cuenta: sirve para recibir dinero.
En lugar de consultar en bucle, registrá una dirección y Conecta te avisa. Cada aviso viaja firmado con el secreto del destino en la cabecera x-conecta-signature y se reintenta hasta seis veces con esperas crecientes si el destino falla. Un mismo hecho puede llegar más de una vez: descartá duplicados por event_id. El orden de llegada no está garantizado.
Verificar la firma antes de procesar
// La firma llega en la cabecera x-conecta-signature
const esperada = crypto
.createHmac("sha256", SECRETO_DEL_DESTINO)
.update(cuerpoCrudoDelAviso)
.digest("hex");
// Compará con la cabecera antes de procesar el avisoTransacciones entrantes
| Evento | Nombre | Cuándo se envía |
|---|---|---|
| payin.received | Transacción entrante recibida | La plataforma recibió una transferencia entrante y la registró. |
| payin.review_required | Transacción entrante que requiere revisión | La entrada no pudo atribuirse automáticamente y quedó retenida en Suspense. |
| payin.credited | Transacción entrante acreditada a una cuenta | El dinero pasó de Suspense a una cuenta virtual concreta. |
| payin.redirected | Transacción entrante reatribuida | La entrada se reatribuyó a otra cuenta virtual de la misma empresa. |
| payin.return_requested | Devolución solicitada | Se solicitó devolver la entrada: el monto queda bloqueado y todavía no sale. |
| payin.return_cancelled | Devolución cancelada | Se canceló la devolución antes de enviarla al riel; el dinero queda donde estaba. |
| payin.return_processing | Devolución en proceso | La devolución se envió al riel: el monto pasó a Devoluciones en tránsito. |
| payin.returned | Transacción entrante devuelta al pagador | La devolución se liquidó y el dinero salió del perímetro. |
| payin.return_failed | Devolución fallida | El riel no pudo devolver: el monto vuelve a Suspense y abre una revisión. |
Transferencias salientes
| Evento | Nombre | Cuándo se envía |
|---|---|---|
| payout.completed | Transferencia saliente ejecutada | Una salida se ejecutó. |
| payout.failed | Transferencia saliente fallida | Una salida falló. |
Maestro de clientes
| Evento | Nombre | Cuándo se envía |
|---|---|---|
| customer.created | Cliente creado | Se dio de alta un cliente en el Maestro, junto con su cuenta virtual principal. |
Cuentas virtuales
| Evento | Nombre | Cuándo se envía |
|---|---|---|
| account.created | Cuenta virtual creada | Se creó una cuenta virtual. |
| account.primary_changed | Cuenta principal del cliente cambiada | El cliente pasó a tener otra cuenta virtual principal. |
| account.suspended | Cuenta virtual suspendida | Se suspendió una cuenta. |
| account.reactivated | Cuenta virtual reactivada | Se reactivó una cuenta. |
| account.fulfilled | Cuenta virtual cumplida | Una cuenta alcanzó su monto esperado. |
| account.expired | Cuenta virtual vencida | Una cuenta venció. |
| account.closed | Cuenta virtual cerrada | Se cerró una cuenta. |
Obligaciones y aplicación de pagos
| Evento | Nombre | Cuándo se envía |
|---|---|---|
| obligation.created | Obligación creada | Se creó una obligación (pago único, plan de cuotas o cobro recurrente). |
| obligation.paid | Obligación completada | Todos los períodos de la obligación quedaron aplicados. |
| installment.paid | Cuota o período pagado | Un período quedó totalmente aplicado. |
| payment.allocated | Pago aplicado | Parte o todo un pago recibido se aplicó a una obligación. |
| payment.unapplied_balance_changed | Saldo sin aplicar actualizado | Cambió el saldo recibido que todavía no tiene destino económico. |
Todo error responde con el mismo formato: code, message, el field que lo provocó cuando aplica, y un request_id para soporte. Los 4xx piden corregir la llamada; ante un 500 o un 503 reintentá con la misma llave de idempotencia.
| Código | HTTP | Cuándo ocurre |
|---|---|---|
| unauthenticated | 401 | Falta la cabecera Authorization. |
| invalid_credential | 401 | La llave no existe o no es válida. |
| credential_revoked | 401 | La llave fue revocada o venció su período de gracia. |
| permission_denied | 403 | La credencial no tiene el permiso que exige el endpoint. |
| company_not_allowed | 403 | La credencial no opera sobre esa empresa. |
| invalid_request | 400 | La petición no es utilizable; por ejemplo, un PATCH sin ningún campo que modificar. |
| invalid_parameter | 400 | Un dato enviado no cumple el formato esperado. |
| missing_parameter | 400 | Falta un dato obligatorio. |
| invalid_cursor | 400 | El cursor de paginación no es válido. |
| unsupported_version | 400 | Se pidió una versión de la API que no existe. |
| idempotency_key_required | 400 | El endpoint exige Idempotency-Key. |
| resource_not_found | 404 | El recurso no existe para esa empresa. |
| duplicate_reference | 409 | Ya existe un recurso con esa referencia externa. |
| resource_conflict | 409 | El recurso cambió de estado y la operación ya no aplica. |
| idempotency_key_reused | 409 | Misma llave con un cuerpo distinto. |
| request_in_progress | 409 | La misma llave está siendo procesada en este momento. |
| account_not_active | 422 | La cuenta no admite la operación en su estado actual. |
| account_lifecycle_closed | 422 | La cuenta está cerrada o archivada: reabrirla es una decisión del portal. |
| insufficient_funds | 422 | La cuenta origen no tiene saldo suficiente. |
| destination_not_registered | 422 | La cuenta bancaria destino no está registrada. |
| beneficiary_name_mismatch | 422 | El titular destino no coincide con la empresa. |
| amount_out_of_range | 422 | El monto supera los límites de la integración. |
| rail_not_enabled | 422 | El riel no está habilitado para esa empresa o corredor. |
| operation_not_available_via_api | 422 | La operación solo se puede realizar en el portal. |
| rate_limit_exceeded | 429 | Se superó el máximo de llamadas por minuto. |
| internal_error | 500 | Error inesperado; volvé a intentar con la misma llave de idempotencia. |
| service_unavailable | 503 | Servicio temporalmente no disponible; reintentá más tarde. |