Recepción de órdenes de cobro
Se ofrece dos modos de recibir peticiones para la emisión de órdenes de cobro a través de SEPA, con el fin de adaptarse a los distintos volúmenes de información a recibir por cada una de las peticiones de los clientes.
Cada una de las peticiones recibidas por este servicio será considerada como una remesa única, aislada e independiente del resto. Será transmitida por EDITRAN al banco configurado de modo automático y no estará vinculada con ninguna de las otras que hayan podido procesarse para el cliente.
Ubicación del servicio
| Entorno Test | Entorno Prod |
|---|---|
| https://test.gestionrecibos.online/api/sepa/neworder | https://app.gestionrecibos.online/api/sepa/neworder |
Estructura del mensaje
El servicio espera recibir un mensaje estructurado, en alto nivel, de la siguiente manera:
Identificación del cliente
Detalles generales remesa SEPA
Órdenes de cobro
Firma del mensaje
| Parámetros | Tipo de dato | Requerido | Descripción |
|---|---|---|---|
| idCliente | Alfanumérico | Si | Identificador del cliente |
| SEPADetails | Estructura | Si | Datos relacionados con la remesa a ejecutar |
| requestDetails | Estructura | Si | Detalle de las órdenes de pago a ejecutar asociadas a la remesa indicada |
| signature | Alfanumérico | Si | Cadena de validación del mensaje |
Detalles generales remesa SEPA / SEPADetails
Este bloque del mensaje específica los detalles de la remesa SEPA que se pretende emitir. La información incluida en este bloque es la siguiente:
Identificación de la remesa: Referencia única asignada por el cliente para la remesa enviada.
Identificador del presentador: código asignado por la entidad bancaria para emitir órdenes de cobro SEPA.
IBAN: Cuenta a favor de la que se ejecutarán las órdenes de cobro
Divisa: Sólo admite el valor ‘978’ (EURO s/ISO-4217)
Fecha de ejecución: Fecha solicitada para la ejecución de las órdenes de cobro
Número total de operaciones: Número de órdenes de cobro incluidas en la remesa
Importe total de las operaciones: Suma del total de las operaciones incluidas en la remesa
Firma: Este bloque contiene una firma separada para la comprobación de su validez.
Esta firma se calculará mediante la concatenación de todos los campos del bloque en el orden en que están enumerados en este documento, incluyendo la clave privada del cliente y aplicando posteriormente la misma técnica que en el resto del servicio.
"SEPADetails":{
"msgIdentifier":"1234567789912K",
"presenterID":"ES90000B812345678",
"creditorIBAN":"ES90000B812345678000",
"collectionDate":"2023-10-03",
"Currency":978,
"submittedOperations":22,
"submittedAmount":2937.54,
"signature":"6C563A5BFA13C1A35AA6F47EC4C91346456023396EF3F737FAF009BB93F88037"
},
| Parámetros | Tipo de dato | Requerido | Descripción |
|---|---|---|---|
| msgIdentifier | Alfanumérico | Si | Cadena con la identificación de la remesa para el cliente |
| presenterID | Alfanumérico | Si | Identificador del presentador SEPA |
| creditorIBAN | Alfanumérico | Si | Cuenta IBAN que recibirá los importes recuperados por la remesa |
| collectionDate | Fecha | Si | Fecha en la que se espera que el banco ejecute la orden |
| currency | Numérico | Si | Sólo admite 978 (EURO) según la normativa ISO-4217 |
| submittedOperations | Numérico | Si | Número total de operaciones comunicadas |
| submittedAmount | Numérico | Si | Suma total de los importes de la remesa |
| signature | Alfanumérico | Si | Cadena de firma de validación del mensaje |
Órdenes de cobro / requestDetails
Una lista con el detalle de las órdenes de cobro a ejecutar
Una URL segura desde la que collectAR podrá obtener un documento con el detalle de las órdenes de pago. El nombre del documento deberá coincidir con la firma de este bloque, independientemente de la extensión configurada.
Una firma que garantice el origen del mensaje
"requestDetails":{
"fileUrl" : "https//:collect-ar/remesas/6128761872618.typeXML",
"typeXML": true,
"signature":"7BE2D3A54514A4E597AB216A4EF9910E82D39FF3661004E6E9971A0441E7BB18"
},
Respuesta del servicio
El servicio devolverá un código de status que indicará el resultado de la petición enviada por el cliente. Si la petición es correcta devolverá también un token que deberá ser utilizado por el cliente en solicitudes posteriores.
| Parámetros | Tipo de datos | Requerido | Descripción |
|---|---|---|---|
| resultado | Numérico | Si | Resultado de la petición |
| token | Cadena | No | Identificador de la remesa |
Los códigos que podrán ser devueltos en el campo resultado son los siguientes:
| Código | Descripción |
|---|---|
| 0 | Petición procesada correctamente |
| 1 | Remesa en cola, pendiente de descarga |
| 1000 | URL de descarga no segura/incorrecta |
| 1001 | No se ha encontrado el documento especificado |
| 1002 | Configuración SEPA incorrecta |
| 1003 | Remesa duplicada |
| 1004 | Remesa pendiente de envío |
| 1005 | Error en los datos del fichero |
| 9000 | Petición errónea |
| 9001 | Firmas del mensaje incoherentes |
| 9998 | Firma del mensaje inválida |
| 9999 | Error no especificado |
Firma del mensaje
La firma se realizará de la siguiente manera. Se concatenan todos los campos de la petición, en el siguiente orden:
idCliente
firma SEPA
firma Detalles ( elemento requestDetails)
Además, se añade también, al final, la clave privada del cliente. Se aplicará una función SHA-256 sobre la cadena anterior
El resultado será codificado en una cadena hexadecimal y convertido a una cadena en mayúsculas.
Ejemplo de petición
{
"idCliente": "bb9e34635fb7",
"SEPADetails":{
"msgIdentifier": "123131232",
"presenterID": "ES123130011234567",
"creditorIBAN": "ES2401821234001234987645",
"collectionDate": "2020-10-17",
"currency": 978,
"submittedOperations": 125,
"submittedAmount": 1345.25,
"signature": "ABC123EEFB2AED6511F1A"
},
"requestDetails":
{
"fileUrl": "https://www.kineox.com/files/sepa/1E2A45FDD4321CBAF",
"typeXML": true,
"signature": "1E2A45FDD4321CBAF"
},
"signature": "AFA3BCADFF5427DAC"
}