Introducción Ultima Actualización: 2022-11-02

Finalitix proporciona un web service con el cual desde cualquier sistema puedes hacer transferencias SPEI.

Registrate en nuestro servicio de integraciones

Puedes hacerlo aquí

Genera tu api key:

La manera de generar un api key es mediante el portal de integraciones es mediante el portal de integraciones

Integración

El servicio API integración esta disponible para todos los clientes que se registren dentro de nuestro portal de integraciones y haya creado una API KEY para su correcta autenticación.

URL del API INTEGRACIÓN: https://integracion.finalitix.com/api/integracion

Crear Paquete de transacciones

Metodo con el cual el servicio cliente puede crear paquetes de transacciones, el cual agrupa las transferencias a realizar de forma conjunta.

URL: https://integracion.finalitix.com/service/v1/batch/

Parámetros

Es una petición REST y deberá ser del tipo “POST”.
x-api-key: Este parametro debe de agregar dentro de HEADER de la petición y es el api key previamente generado desde el portal de integraciones.
nombre: que es el nombre con el que se desea nombrar el paquete de transacciones
cantidad_operaciones: Es la cantidad de operaciones que el paquete puede tener, este parametro es opcional, cuando no se pone el paquete no tiene limite de transacciones

Ejemplo de petición:

Lenguaje utilizado en el ejemplo es Node JS

								
var axios = require('axios');
var data = JSON.stringify({
	"nombre": "Nombre del paquete", 
	"cantidad_operaciones": 20
});
var config = {
method: 'post',
url: 'https://integracion.finalitix.com/service/v1/batch/',
headers: {
'x-api-key': 'abcdef12345',
'Content-Type': 'application/json'
},
data : data
};
//llamada utilizando axios
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});

Ejemplo de respuesta:

								
{
	"success": true,
	"message": "Paquete creado correctamente",
	"result": {
		"name":"Nombre del paquete",
		"paquete_id": "8f67c9a6-c304-4247-be22-08ace4e0fa09"
	}
}

Editar Paquete de transacciones

Metodo con el cual el servicio cliente puede editar la cantidad de operaciones de un paquetes de transacciones.

URL: https://integracion.finalitix.com/service/v1/batch/

Parámetros

Es una petición REST y deberá ser del tipo “PUT”.
x-api-key: Este parametro debe de agregar dentro de HEADER de la petición y es el api key previamente generado desde el portal de integraciones.
paquete_id: Este parametro debe incluir el identificador del paquete que se desea editar
cantidad_operaciones: Este parametro deve incluir la nueva cantidad que tendra el paquete, si ya se establecio al crear el paquete este parametro no puede ser cero

Ejemplo de petición:

Lenguaje utilizado en el ejemplo es Node JS

								
var axios = require('axios');
var data = JSON.stringify({
	"paquete_id": "8f67c9a6-c304-4247-be22-08ace4e0fa09", 
	"cantidad_operaciones": 30
});
									
var config = {
method: 'put',
url: 'https://integracion.finalitix.com/service/v1/batch/',
headers: {
'x-api-key': 'abcdef12345',
'Content-Type': 'application/json'
},
data : data
};
									
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});

Ejemplo de respuesta:

								
{
	"success": true,
	"message": "Paquete creado correctamente",
	"result": {
		"paquete_id": "8f67c9a6-c304-4247-be22-08ace4e0fa09",
		"cantidad_operaciones": 30
	}
}

Eliminar Paquete de transacciones

Metodo con el cual el servicio cliente puede eliminar un paquete de transacciones. (el paquete no se puede eliminar si ya tiene transacciones o si ya ha sido procesado).

URL: https://integracion.finalitix.com/service/v1/batch/delete-package

Parámetros

Es una petición REST y deberá ser del tipo “POST”.
x-api-key: Este parametro debe de agregar dentro de HEADER de la petición y es el api key previamente generado desde el portal de integraciones.
paquete_id: Este parametro debe incluir el identificador del paquete que se desea editar

Ejemplo de petición:

Lenguaje utilizado en el ejemplo es Node JS

								
var axios = require('axios');
var data = JSON.stringify({
	"paquete_id": "8f67c9a6-c304-4247-be22-08ace4e0fa09", 
});
									
var config = {
method: 'post',
url: 'https://integracion.finalitix.com/api/integracion/delete-package',
headers: {
'x-api-key': 'abcdef12345',
'Content-Type': 'application/json'
},
data : data
};
									
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});

Ejemplo de respuesta:

								
{
	"success": true, 
	"message": "Se ha eliminado el lote con exito"
}

Transacciones

El Modulo de transacciones el el que interactua entre finalitix y el portal de integracion para dar a conocer las operaciones que seran procesadas.

Agregar Transacciones a un paquete

Este metodo es el encargado de darle a conocer a finalitix cuales son las transferencia que se realizarán.

URL: https://integracion.finalitix.com/service/v1/batch/add-operation

Parámetros

Es una petición REST y deberá ser del tipo “POST”.
x-api-key: Este parametro tiene que ser agregado al HEADER de la petición y es el api key previamente generado desde el portal de integraciones.
nombre_beneficiario: Nombre de la persona fisica o moral que sera quien reciba los fondos enviados.
clabe: Este parametro debe incluir Cuenta clabe del beneficiario (esta cuenta clabe debe existir como un contacto dentro del portal finalitix.
importe: Este parametro debe incluir el importe a transferir en la operación
paquete_id: Este parametro debe incluir el paquete al que pertenece la transacción

Ejemplo de petición:

Lenguaje utilizado en el ejemplo es Node JS

								
var axios = require('axios');
var data = JSON.stringify({
  "nombre_beneficiario": "Nombre completo del beneficiario",
  "clabe": "123456789876543212",
  "importe": 1000,
  "package_id": "8f67c9a6-c304-4247-be22-08ace4e0fa09"
});

var config = {
  method: 'post',
  url: 'https://integracion.finalitix.com/service/v1/batch/add-operation',
  headers: { 
	'x-api-key': 'abcdef12345', 
	'Content-Type': 'application/json'
  },
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Ejemplo de respuesta:

								
{
	"success": true,
	"message": "Operacion creada correctamente",
	"result": {
		"paquete_id":"8f67c9a6-c304-4247-be22-08ace4e0fa09",
		"operacion_id": "1",
		"transaction_estatus": "draft" /* Siempre sera el mismo estatus */
	}
}

Editar Transacciones

Este metodo se encarga de editar el importe de una operacion antes creada.

URL: https://integracion.finalitix.com/service/v1/batch/edit-operation

Parámetros

Es una petición REST y deberá ser del tipo “POST”.
x-api-key: Este parametro tiene que ser agregado al HEADER de la petición y es el api key previamente generado desde el portal de integraciones.
operacion_id: Este parametro debe incluir el identificador de la transacción
importe: Este parametro debe incluir el importe a transferir en la operación
paquete_id: Este parametro debe incluir el paquete al que pertenece la transacción

Ejemplo de petición:

Lenguaje utilizado en el ejemplo es Node JS

								
var axios = require('axios');
var data = JSON.stringify({
  
  "operacion_id": "1",
  "importe": 500.80,
  "package_id": "8f67c9a6-c304-4247-be22-08ace4e0fa09"
});

var config = {
  method: 'post',
  url: 'https://integracion.finalitix.com/service/v1/batch/edit-operation',
  headers: { 
	'x-api-key': 'abcdef12345', 
	'Content-Type': 'application/json'
  },
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Ejemplo de respuesta:

								
{
	"success": true,
	"message": "Transacción editada",
	"result": {
		"paquete_id":"8f67c9a6-c304-4247-be22-08ace4e0fa09",
		"operacion_id": "1",
		"updated": "true" /* true, false */
	}
}

Eliminar Transacciones

Este metodo se encarga de eliminar una transacción de un paquete de transacciones

URL: https://integracion.finalitix.com/service/v1/batch/delete-operation

Parámetros

Es una petición REST y deberá ser del tipo “POST”.
x-api-key: Este parametro tiene que ser agregado al HEADER de la petición y es el api key previamente generado desde el portal de integraciones.
operacion_id: Este parametro debe incluir el identificador de la transacción
paquete_id: Este parametro debe incluir el paquete al que pertenece la transacción

Ejemplo de petición:

Lenguaje utilizado en el ejemplo es Node JS

								
var axios = require('axios');
var data = JSON.stringify({
  "operacion_id": "1",
  "package_id": "8f67c9a6-c304-4247-be22-08ace4e0fa09"
});

var config = {
  method: 'post',
  url: 'https://integracion.finalitix.com/service/v1/batch/delete-operation',
  headers: { 
	'x-api-key': 'abcdef12345', 
	'Content-Type': 'application/json'
  },
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Ejemplo de respuesta:

								
{
	"success": true,
	"message": "Transacción eliminada",
	"result": {
		"paquete_id":"8f67c9a6-c304-4247-be22-08ace4e0fa09",
		"operacion_id": "1",
		"deleted": true /* true, false */
	}
}

Listado de transferencias

Este metodo se encarga mostrar un listado de las transferencias que tiene un paquete.

URL: https://integracion.finalitix.com/service/v1/batch/list-operations

Parámetros

Es una petición REST y deberá ser del tipo “POST”.
x-api-key: Este parametro tiene que ser agregado al HEADER de la petición y es el api key previamente generado desde el portal de integraciones.
paquete_id: Este parametro debe incluir el paquete al que pertenece la transacción

Ejemplo de petición:

Lenguaje utilizado en el ejemplo es Node JS

								
var axios = require('axios');
var data = JSON.stringify({
  "paquete_id": "8f67c9a6-c304-4247-be22-08ace4e0fa09"
});

var config = {
  method: 'post',
  url: 'https://integracion.finalitix.com/service/v1/batch/list-operations',
  headers: { 
	'x-api-key': 'abcdef12345', 
	'Content-Type': 'application/json'
  },
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Ejemplo de respuesta:

								
{
	"success": true,
	"message": "Lista de transacciones del paquete: 8f67c9a6-c304-4247-be22-08ace4e0fa09",
	"result": {
		"paquete_id":"8f67c9a6-c304-4247-be22-08ace4e0fa09",
		"operations": [
			{
				"nombre_beneficiario": "Nombre completo del beneficiario",
				"clabe": "123456789876543212",
				"importe": 500.80,
			},
			{
				"nombre_beneficiario": "Nombre completo del beneficiario",
				"clabe": "123456789876543213",
				"importe": 3000,
			}
		],
	}
}

Crear abono en espera

Este metodo se encarga de generar un abono esperado por un cliente, cuando finalitix detecte un abono a su cuenta revisara estos abonos para revisar si corresponde a un de ellos, en caso contrario los tomara como anticipos.

URL: https://integracion.finalitix.com/service/v1/batch/draft-payment

Parámetros

Es una petición REST y deberá ser del tipo “POST”.
x-api-key: Este parametro tiene que ser agregado al HEADER de la petición y es el api key previamente generado desde el portal de integraciones.
rfc: Este parametro debe incluir el RFC del cliente que desea crear un abono esperado.
monto: Este parametro debe incluir el monto del abono esperado.
ordenante: Este parametro debe incluir el nombre del ordenante que realiza el abono.
concepto: Este parametro debe incluir el concepto del abono.

Ejemplo de petición:

Lenguaje utilizado en el ejemplo es Node JS

								
var axios = require('axios');
var data = JSON.stringify({
  "rfc": "XAXX010101000",
	"monto": 1050.50,
	"ordenante": "John Doe",
	"concepto": "Pago por x servicio"
});

var config = {
  method: 'post',
  url: 'https://integracion.finalitix.com/service/v1/batch/draft-payment',
  headers: { 
	'x-api-key': 'abcdef12345', 
	'Content-Type': 'application/json'
  },
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Ejemplo de respuesta:

								
{
	"success": true,
	"message": "Se ha creado un abono esperado",
}

Obtener URL

En este modulo el API de integraciones gestiona los URL personalizados que se usan para enlazar el servicio cliente con el portal finalitix.

Generar URL de Pago

Este metodo genera una url personalizada para el el cliente final pueda acceder con sus credenciales y realizar las transferencias desde el portal de finalitix.

URL: https://integracion.finalitix.com/api/integracion/get-url

Parámetros

Es una petición REST y deberá ser del tipo “POST”.
x-api-key: Este parametro tiene que ser agregado al HEADER de la petición y es el api key previamente generado desde el portal de integraciones.
paquete_id: Este parametro debe incluir el paquete al que pertenece la transacción

Ejemplo de petición:

Lenguaje utilizado en el ejemplo es Node JS

								
var axios = require('axios');
var data = JSON.stringify({
  "paquete_id": "8f67c9a6-c304-4247-be22-08ace4e0fa09"
});

var config = {
  method: 'post',
  url: 'https://integracion.finalitix.com/api/integracion/get-url',
  headers: { 
	'x-api-key': 'abcdef12345', 
	'Content-Type': 'application/json'
  },
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Ejemplo de respuesta:

								
{
	"paquete_id":"8f67c9a6-c304-4247-be22-08ace4e0fa09",
	"url": "https://finalitix.com/auth/login/b55b20a3636c91fb211baa5944103a37",
	"status": "1" /* 1 = available, 2 = done, 3 = expired */
}

Notificaciones

En esta sección encontraras lo que necesitas saber para recibir notificaciones en tiempo real de las operaciones que estas realizando desde Finalitix.

Este funcionamiento funciona mediante el uso de Webhooks, los cuales son peticiones enviadas a una URL específica cada vez que se realiza una operación en Finalitix.

Los webhooks deben ser creados por el cliente y deben ser activados para que funcionen.

Abonos / Anticipos

Esta funcionalidad permite recibir notificaciones de anticipos de clientes y/o abonos a la cuenta de Finalitix.

Finalitix envía información

Parámetros Enviados

Es una petición REST y deberá ser del tipo “POST”.
fecha: Este parametro icluye la fecha en formato yyyy-MM-dd hh:mm:ss en la que se recibió el abono.
nombre_ordenante: Este parametro es el nombre del ordenante que realiza el abono.
monto: Este parametro es el monto del abono.
rfc_curp_ordenante: Este parametro es el RFC o CURP de la cuenta del ordenante que realiza el abono.
abono_precargado_id: Este parametro nos indica si finalitix ha encontrado este abono dentro de los abonos esperados por el cliente. (si es 0 significa que no se encontro el abono)
operacion_cliente_id: Este parametro indica el id de la operacion del cliente con la que se ha enlazado el abono.
cuenta_ordenante: Este parametro es la cuenta del ordenante que realiza el abono.

Ejemplo de notificacion enviada:

Lenguaje utilizado en el ejemplo es Node JS

								
{
	fecha: "2020-01-01",
	nombre_ordenante: "John Doe",
	monto: 1000,
	rfc_curp_ordenante: "XXXXXXXXXXXX",
	abono_precargado_id: true || false,
	operacion_cliente_id: 1 , // id o null
	cuenta_ordenante: "123456789",
}

Lote de cargos procesados

Esta funcionalidad permite recibir notificaciones sobre los lotes de transacciones procesados por Finalitix.

Finalitix envía información

Parámetros Enviados

Es una petición REST y deberá ser del tipo “POST”.
fecha: Este parametro icluye la fecha en formato yyyy-MM-dd hh:mm:ss en la que se recibió el abono.
procesado: Este parametro indica si el lote de cargos ha sido procesado o no.
mensaje: Este parametro indica el mensaje de exito o no al procesar el lote de cargos.
transaciones_procesadas: Este parametro es un arreglo con los ids de las transacciones procesadas.
transacciones_no_procesadas: Este parametro es un arreglo con los ids de las transacciones no procesadas y muestra el motivo de no procesarse.
monto_total_transacciones_procesadas: Este parametro indica el monto total de las transacciones procesadas.
monto_total_transacciones_no_procesadas: Este parametro indica el monto total de las transacciones no procesadas.

Ejemplo de notificacion enviada:

Lenguaje utilizado en el ejemplo es Node JS

								
{
	fecha: "2020-01-01",
	procesado: true || false, // siempre que haya una transaccion no procesada, se devuelve false
	mensaje: "Mensaje de error" || "Mensaje de exito",
	transaciones_procesadas: [{cliente_operacion_id: 1 }],
	transacciones_no_procesadas: [{cliente_operacion_id: 2, mensaje: "fondos insuficientes" || "otro error"}],
	monto_total_transacciones_procesadas: 1000,
	monto_total_transacciones_no_procesadas: 1000,
}

Destinatarios creados

Esta funcionalidad permite recibir notificaciones cuando se crean los destinatarios desde las transacciones generadas por esta integración.

Finalitix envía información

Parámetros Enviados

Es una petición REST y deberá ser del tipo “POST”.
id_destinatario: Este parametro indica el id del destinatario que se ha creado.
nombre_destinatario: Este parametro indica el nombre del destinatario que se ha creado.
rfc_destinatario: Este parametro indica el RFC del destinatario que se ha creado.
cuenta_clabe: Este parametro indica la cuenta clabe del destinatario que se ha creado.

Ejemplo de notificacion enviada:

Lenguaje utilizado en el ejemplo es Node JS

								
{
	id_destinatario: 1,
	nombre_destinatario: "John Doe",
	rfc_destinatario: "XXXXXXXXXXXX",
	cuenta_clabe: "123456789",
}