[go: up one dir, main page]

Documentación del API de validación de códigos de sucursal y cuentas bancarias V4

Este API es parte de nuestro servicio SortWare

1. ¿Qué es el API de SortWare V4?

El API de SortWare proporciona automatización para validar el código de sucursal y los números de cuenta del Reino Unido.

El API proporciona dos funciones principales "búsqueda" y "validación". La función'validar' realiza la validación de módulos con una combinación de código de sucursal y número de cuenta.
En caso de que necesite buscar un código de sucursal en el directorio bancario, puede utilizar la función "buscar" y recuperar la información del banco y de la sucursal para ese código de sucursal específico.

Registro de cambios (de v3 a v4):


Nueva estructura de respuesta
La nueva versión de la API de SortWare ahora proporciona una estructura de respuesta mejorada en formato XML y JSON.
Separamos los resultados en cinco elementos (datos de cuenta, datos bancarios, esquemas de pago, validaciones y errores)
La estructura es muy similar a la de nuestra API de validación IBAN, lo que facilita la integración cuando se utilizan nuestras dos soluciones. Puede encontrar una descripción detallada de la estructura de respuesta a continuación (ver sección 4. Estructura de Respuesta API)

Códigos de error
Se implementaron códigos de error en la respuesta de SortWare V4 para facilitar el análisis de los resultados de validación y las respuestas del API.
Al igual que con nuestros otros API, los códigos de error devuelven un formato legible por máquinas para todos los errores que la API V4 pueda encontrar.
Consulte la sección 5. (Códigos de error) para obtener una descripción detallada de los códigos de error devueltos por el sistema.

Funcionalidad mejorada de cálculo de IBAN
Presentamos un nuevo y mejorado algoritmo para calcular el IBAN a partir de los datos de código de sucursal y número de cuenta tanto para el Reino Unido como para Irlanda.
La nueva funcionalidad utiliza nuestro preciso directorio de códigos bancarios para calcular los IBAN con mayor precisión y con menor posibilidad de errores durante el cálculo.



2. Características

El API SortWare cuenta con las siguientes características clave:

  • Recuperar información sobre el banco y la sucursal a partir del código de sucursal.
  • Generar automáticamente un IBAN válido para el código de sucursal y el número de cuenta suministrados.
  • Identificar el soporte de pagos FPS/CHAPS y Direct Debit para el banco y sucursal asociado con el código de sucursal suministrado.
  • Se muestran distintos resultados en una respuesta XML y JSON de fácil codificación.

3. Uso del API

Este API le permite automatizar la validación de código de sucursal y número de cuenta a través de una sola solicitud HTTP GET o POST.

Los parámetros aceptados se enumeran en la tabla siguiente:

Nombre del campo Longitud Tipo Descripción
format 4 Cadena Este parámetro puede ser uno de los dos formatos admitidos 'xml' o 'json'. Especifica el formato de la respuesta.
search 6 Cadena Este parámetro se puede utilizar para buscar un código de sucursal en nuestro directorio bancario.
sortcode 6 Cadena El código de sucursal proporcionado para la validación en combinación con el parámetro "account".
account 8 Cadena Número de cuenta bancaria proporcionado para la validación en combinación con el parámetro "sortcode".
api_key 128 Cadena Su llave API personal usada para asegurar el acceso al sistema.
Dentro de la sección Área de cliente -> Acceso al API encontrará su llave API, que se utiliza para identificar su cuenta durante las solicitudes de API.

Preparamos ejemplos de cómo enviar una solicitud basada en POST a nuestro API en los idiomas más comunes:

curl "https://api.iban.com/clients/api/v4/sort/" \
    -X POST \
    -d format=json \
	-d api_key=[YOUR_API_KEY] \
	-d sortcode=200415 \
	-d account=38290008 
<?php
$curl = curl_init();

$post = [
    'format' => 'json',
    'api_key' => '[YOUR_API_KEY]',
    'sortcode'   => '200415',
	'account' => '38290008',
];

curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://api.iban.com/clients/api/v4/sort/',
	CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS => $post
));

$output = curl_exec($curl);
$result = json_decode($output);

print_r($result);

curl_close($curl);
?>
require 'net/http'

uri = URI('https://api.iban.com/clients/api/v4/sort/')

res = Net::HTTP.post_form(uri, "format" => "json", "api_key" => "[YOUR_API_KEY]","sortcode" => "200415","account" => "38290008")

puts res.body
import requests

post_data = {'format':'json', 'api_key':'[YOUR_API_KEY]','sortcode':'200415','account':'38290008'}

response = requests.post('https://api.iban.com/clients/api/v4/sort/',post_data)
print(response.text)
use LWP::UserAgent;

my $ua = LWP::UserAgent->new;
my $server_endpoint = "https://api.iban.com/clients/api/v4/sort/";

my $format = 'json';
my $api_key = '[YOUR_API_KEY]';
my $sortcode = '200415';
my $account = '38290008';


my $req = HTTP::Request->new( POST => $server_endpoint );
$req->content_type('application/x-www-form-urlencoded');

my $post_data = 'format=' . $format . '&api_key=' . $api_key . '&sortcode=' . $sortcode . '&account=' . $account;

$req->content($post_data);

my $resp = $ua->request($req);

if ( $resp->is_success ) {
    my $message = $resp->decoded_content;
	print $message;
}

JAVA

import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
import org.json.simple.JSONObject;
import org.json.simple.JSONArray;
import org.json.simple.parser.ParseException;
import org.json.simple.parser.JSONParser;


public class ibanapi {

	private final String USER_AGENT = "API Client/1.0";

	public static void main(String[] args) throws Exception {

		ibanapi http = new ibanapi();

		
		System.out.println("\nTesting API - Send API POST request");
		http.sendPost();

	}

	// HTTP POST request
	private void sendPost() throws Exception {

		String url = "https://api.iban.com/clients/api/v4/sort/";
		URL obj = new URL(url);
		HttpsURLConnection con = (HttpsURLConnection) obj.openConnection();

		//add reuqest header
		con.setRequestMethod("POST");
		con.setRequestProperty("User-Agent", USER_AGENT);
		con.setRequestProperty("Accept-Language", "en-US,en;q=0.5");

		String urlParameters = "api_key=[YOUR_API_KEY]&format=json&sortcode=200415&account=38290002";

		// Send post request
		con.setDoOutput(true);
		DataOutputStream wr = new DataOutputStream(con.getOutputStream());
		wr.writeBytes(urlParameters);
		wr.flush();
		wr.close();

		int responseCode = con.getResponseCode();
		System.out.println("\nSending 'POST' request to URL : " + url);
		System.out.println("Post parameters : " + urlParameters);
		System.out.println("Response Code : " + responseCode);

		BufferedReader in = new BufferedReader(
		new InputStreamReader(con.getInputStream()));
		String inputLine;
		StringBuffer response = new StringBuffer();

		while ((inputLine = in.readLine()) != null) {
			response.append(inputLine);
		}
		in.close();

		//print result
		System.out.println(response.toString());

	}

}

.NET

public static void Main(string[] args)
		{						
			var request = (HttpWebRequest)WebRequest.Create("https://api.iban.com/clients/api/v4/sort/");
 
			var postData = "api_key=[YOUR_API_KEY]";
			 postData += "&format=json";
			 postData += "&sortcode=200415";
			 postData += "&account=38290002";
			 
			var data = Encoding.ASCII.GetBytes(postData);
			 
			request.Method = "POST";
			request.ContentType = "application/x-www-form-urlencoded";
			request.ContentLength = data.Length;
			 
			using (var stream = request.GetRequestStream())
			{
			 stream.Write(data, 0, data.Length);
			}
			 
			var response = (HttpWebResponse)request.GetResponse();
			 
			var responseString = new StreamReader(response.GetResponseStream()).ReadToEnd();
			
			Console.WriteLine(responseString);
			
			Console.Write("Press any key to continue . . . ");
			Console.ReadKey(true);
		}

NODE

var request = require('request');

var headers = {
    'User-Agent':       'IBAN API Client/0.0.1',
    'Content-Type':     'application/x-www-form-urlencoded'
}

var options = {
    url: 'https://api.iban.com/clients/api/v4/sort/',
    method: 'POST',
    headers: headers,
    form: {'api_key': '[YOUR_API_KEY]', 'format': 'json', 'sortcode': '200415', 'account': '38290002'}
}


request(options, function (error, response, body) {
    if (!error && response.statusCode == 200) {
     
		var data = JSON.parse(body);

		console.log(data.errors);
		
		console.log("Bank Name: " + data.bank_data.bank);
		console.log("Bank BIC: " + data.bank_data.bic);
		console.log("Bank City: " + data.bank_data.city);
		console.log("Bank Address: " + data.bank_data.address);
		console.log("Bank Zip: " + data.bank_data.zip);
		console.log("Bank Phone: " + data.bank_data.phone);
		console.log("Bank Country Name: " + data.bank_data.country);
		console.log("IBAN: " + data.account_data.iban);
		
    }
})



4. Estructura de respuesta del API

La respuesta del API de SortWare V4 contiene algunos objetos de datos para ayudar a separar claramente las diferentes características de los datos devueltos.
No dude en hacer referencia al esquema XSD para la respuesta en formato XML a continuación:

  
    
      
        
          
            
              
              
              
            
          
        
        
          
            
              
              
              
              
              
              
              
              
            
          
        
        
          
            
              
              
              
              
              
            
          
        
        
          
            
              
                
                  
                    
                    
                  
                
              
            
          
        
        
      
    
  

A continuación, puede encontrar descripciones detalladas de los tipos de elementos de datos devueltos en cada objeto de datos individual:

Descripción del objeto "account_data"
Nombre del campo Longitud Tipo Descripción
SORTCODE 6 Entero Devuelve el código de sucursal que el cliente envió para su consulta.
ACCOUNT 8 Entero Contiene el número de cuenta enviado por el cliente.
IBAN 125 Cadena Contiene el número de cuenta bancaria internacional (IBAN) calculado a partir del código de sucursal y el número de cuenta válidos proporcionados.


Descripción del objeto "bank_data" que contiene información sobre el banco emisor y la sucursal del código de sucursal enviado.
Nombre del campo Longitud Tipo Descripción
BIC 8 or 11 Cadena El código BIC del banco y de la sucursal correspondiente.
BANK 256 Cadena El nombre del banco al que pertenece el código de sucursal enviado.
BRANCH 256 Cadena Nombre de la sucursal bancaria específica a la que se asignó el código de sucursal.
ADDRESS 256 Cadena Dirección de la sucursal bancaria correspondiente a la que pertenece el código de sucursal.
CITY 11 Cadena Nombre de la ciudad donde se ubica la sucursal correspondiente.
ZIP 11 Cadena Código postal de la dirección de la sucursal bancaria.
PHONE 20 Cadena Número telefónico de contacto para el banco y la sucursal correspondientes.
COUNTRY 2 Cadena Código ISO de dos letras del país donde se ubican el banco y la sucursal.


Descripción del objeto "payment_schemes" que proporciona información acerca de los esquemas de pago admitidos
Nombre del campo Longitud Tipo Descripción
DD 3 Cadena Indicador de compatibilidad con Direct Debit en la sucursal correspondiente. Los valores pueden ser "SÍ" o "NO".
FPS_PAYMENTS 3 Cadena Indicador de compatibilidad con Faster Payments Service en la sucursal correspondiente. Los valores pueden ser "SÍ" o "NO".
CHAPS 3 Cadena Indicador de compatibilidad con CHAPS en la sucursal correspondiente. Los valores pueden ser "SÍ" o "NO".
BACS 3 Cadena Indicador de compatibilidad con BACS en la sucursal correspondiente. Los valores pueden ser "SÍ" o "NO".
CCC_PAYMENTS 3 Cadena Indicador de compatibilidad con Cheque and Credit Clearing Company (C&CCC) en la sucursal correspondiente. Los valores pueden ser "SÍ" o "NO".


Descripción del objeto "validations"
Nombre del campo Longitud Tipo Descripción
CODE 3 Entero Devuelve el código de estado de la validación de módulo realizada con la combinación de código bancario y número de cuenta. Consulte la sección 5 (códigos de acceso) para ver una descripción de los valores.
MESSAGE 256 Cadena Contiene la descripción de texto de los resultados de validación. Consulte la sección 5 (códigos de estado) para ver todos los resultados posibles.


Descripción del objeto "errors"
Nombre del campo Longitud Tipo Descripción
CODE 3 Entero Devuelve el código de estado del error si ha ocurrido uno. Consulte la sección 5 (códigos de estado) para ver una descripción de los valores.
MESSAGE 256 Cadena Contiene la descripción de texto de los resultados de validación. Consulte la sección 5 (códigos de estado) para ver todos los resultados posibles.


5. Códigos de estado del API SortWare V4

Hay dos tipos de códigos de estado que devuelve el API.
El objeto de datos "validations" devuelve el éxito o fracaso del proceso de validación.
El objeto "errors" devuelve los errores de cuenta.

Código de estado Tipo Descripción
301 Error de cuenta Llave API inválida
302 Error de cuenta Suscripción expirada
303 Error de cuenta No hay consultas disponibles
304 Error de cuenta No tiene acceso a este API
201 Validación fallida El dígito de verificación del número de cuenta no es correcto
202 Validación fallida Código de sucursal no encontrado en el directorio del banco
001 Validación correcta El dígito de verificación del número de cuenta es válido