¿Cómo realizar la integración mediante API?

Las API funcionan como un canal de comunicación entre ambos sistemas; es a demanda, es decir, desde tu sistema deben hacer una petición con la API Key correspondiente.

Por ejemplo, puedes usar la API para crear o actualizar clientes, enviar órdenes de pago, reportar pagos, consultar saldos, etc.

La API Key es una clave única que identifica a tu sistema al conectarse con Moonflow. Funciona como una llave de acceso para que puedas transferir información de forma segura entre sistemas.

Ten en cuenta que:

• Puedes configurar los permisos que tiene cada clave (por ejemplo, solo crear clientes o solo consultar saldos).

• Puedes tener varias claves activas al mismo tiempo, con distintos permisos.

💡 Accede a la documentación técnica con instrucciones para configurar la conexión haciendo clic aquí.

1. Ve a la parte superior derecha del Dashboard y haz clic en Ajustes (ícono del engranaje ⚙️).

2. Selecciona la sección Integraciones.

3. En la pestaña Métodos de integración, selecciona API.

4. Allí podrás ver la lista de todas las API Key que generes. Además, verás un botón que dice Ir a la documentación.

5. Si quieres crear una nueva, haz clic en Añadir.

6. Asígnale un nombre a la conexión y configura sus permisos.

7. Haz clic en Guardar. Una vez hecho esto, tendrás acceso a tu API Key.

Si optas realizar la integración mediante API, puedes elegir entre 2 métodos de procesamiento: online (procesa hasta 20 registros por minuto, en tiempo real) y batch (procesa datos en bloques, hasta 5.000 registros por solicitud).

💡 Aprende más sobre estos en el siguiente artículo: Procesamiento de datos: Online vs Batch .

Asegúrate de enviar los datos en el cuerpo de la solicitud HTTP (body) utilizando el formato JSON adecuado. No debes incluir los datos como parámetros en la URL (params), ya que esto puede generar errores en el procesamiento de la información.

Por ejemplo, para crear una orden de pago, utiliza una solicitud POST con el siguiente formato:

{
    "documentTypeId": 400,
    "documentNumber": "987654321",
    "paymentCode": "987654321-1",
    "currency": "USD",
    "amount": 10,
    "dueDate": "2023-05-01",
    "productName": null,
    "feesAndPenalties": 1,
    "discount" : 2,
    "externalClientId": "987654321",
    "quota": 3,
    "issuedDate" : "2022-05-01",
    "attachment1" : null,
    "attachment2" : null,
    "description" : "Lorem ipsum dolor sit amet, consectetur adipiscing elit",
    "deleted" : false,
    "externalOrderId" : null,
    "customVariables" : {}
}
          

Evita enviar los datos de esta manera:

POST /api/paymentorder?documentNumber=12345678&amount=100.0&dueDate=2025-06-30
          

Te recomendamos utilizar el modo API Batch. Este formato permite enviar hasta 5.000 objetos por solicitud y se procesa de forma asíncrona, lo que mejora la eficiencia del intercambio de datos.

Moonflow acepta hasta 20 peticiones por minuto. Si superas este límite, recibirás un error de respuesta.

Cada lote genera un batchId, que puedes consultar para verificar el estado del procesamiento. Si hay errores, el sistema te mostrará la posición y el detalle del problema. Consulta la sección 1.6.1 de la documentación técnica aquí para más información.

💡 Recuerda: Esta integración requiere que tu sistema esté preparado para enviar la información estructurada según los campos que Moonflow espera recibir. Si tu ERP o CRM tiene limitaciones, revisa con tu equipo técnico qué datos pueden sincronizarse y cómo adaptarlos al formato necesario.

No. Puedes crear y usar tantas claves API como necesites.

Pueden estar activas al mismo tiempo y cada una puede tener permisos distintos, como si fueran usuarios.

Por ejemplo:

• Una clave para un sistema que solo crea órdenes de pago.

• Otra clave para otro sistema que solo actualiza clientes.

Si te integras a Moonflow por 2 interfases, es clave que sepas cómo enviar correctamente los campos amount y balance.

El amount es el monto total original de la cuota o deuda. Debe incluir capital, intereses pactados desde el comienzo con el cliente, etc. No deberías sumar mora en este campo.

El balance es el saldo pendiente a pagar de esa cuota o deuda. Si la cuota tiene mora acumulada o pagos parciales, este valor puede ser distinto al amount.

💡 Accede a tips y recomendaciones sobre este tema en el siguiente artículo: Manejo de amount y balance en la integración por API.

Error 500: ocurre cuando algo falla en el servidor al procesar la solicitud. Es un error interno que no depende de los datos que enviaste.

Error 401: ocurre si el token no es válido.

Error 403: aparece cuando se alcanzó el límite de uso o no se tiene acceso al endpoint.

Error 409: indica un conflicto con los datos enviados.