Fonctionnement
L'API SepaWin vous permet de générer des buffers de données ou des fichiers au format XML à partir de 3 requêtes web simples:
Création d'une transaction de virement ou de prélèvement
Ajout de lignes dans la transaction
Génération du résultat sous forme d'un fichier ou d'un buffer de données
Préalable
Avoir créé une licence API SepaWin avec les éléments suivants:
Votre IBAN (qui constitue la clé de licence SepaWin)
Votre BIC
Votre RAISON SOCIALE
Votre NUMERO DE SIRET
Votre ICS (Identifiant de créancier SEPA : uniquement si vous souhaitez effectuer des prélèvements)
Création d'une transaction
Appeler l'url « https://www.sepawin.com/api/ » avec les arguments GET suivants:
a : « start »
i : Votre IBAN (qui constitue la clé de licence SepaWin)
t : Type de transaction : « virement » ou « prelevement »
r : Référence de la transaction : 30 caractères alphanumériques maximum, pas d'accents ni de caractères spéciaux
d : Date d'exécution au format 06/12/2024
Le retour est au format JSON et se compose de deux données:
status : « ok » ou erreur spécifiée
transaction : identifiant unique de transaction (uniquement disponible si le status est « ok »)
Exemple de création de transaction en PHP:
$iban = "Votre clé de licence";
$return = file_get_contents( "https://www.sepawin.com/api/?a=start&i=".$iban."&t=virement&r=ma+reference&d=06/12/2024" );
$return = json_decode($return);
if( is_object($return) && $return->statut=="ok" )
{
// Ok
print_r( $return );
}
Affiche :
stdClass Object
(
[statut] => ok
[transaction] => 82
)
Ajout de lignes dans la transaction
Appeler l'url « https://www.sepawin.com/api/ » avec les arguments GET suivants:
a : « add »
i : Votre IBAN (qui constitue la clé de licence SepaWin)
t : Identifiant de transaction : Valeur retournée par l'appel API « start »
m : Montant de la ligne au format 00.00 ou 00,00
d : IBAN destinataire
b : BIC destinataire
n : Nom du destinataire : 30 caractères alphanumériques maximum, pas d'accents ni de caractères spéciaux
l : Libellé de la transaction : 30 caractères alphanumériques maximum, pas d'accents ni de caractères spéciaux
r : RUM : (uniquement obligatoire pour les prélèvements)
s : Date de signature du mandat : au format 06/12/2024 (uniquement obligatoire pour les prélèvements)
f : Traiter cette ligne en FRST (*) ou en RCUR ? « 1 » pour FRST. Toute autre valeur pour RCUR. (uniquement obligatoire pour les prélèvements)
e : Date d'échéance : au format 06/12/2024. Remplace la date d'exécution d'entête si renseignée. (optionnel, et uniquement pour les prélèvements)
18/09/2020 : ajout du code pays et de l'adresse postale du bénéficiaire du virement
c : Code pays au format ISO 3166 à 2 caractères (code alpha-2) : (optionnel, et uniquement pour les virements) liste des codes pays
p : Adresse postale du bénéficiare (optionnel, et uniquement pour les virements)
26/10/2022 : ajout du code postal et de la ville du bénéficiaire du virement
q : Code postal du bénéficiare (optionnel, et uniquement pour les virements)
v : Ville du bénéficiare (optionnel, et uniquement pour les virements)
Le code pays, l'adresse postale, le code postal et la ville permettent de transférer les coordonnées d'un bénéficiare d'un virement et sont nécessaires pour les destinataires en dehors de la zone EEE (Suisse, Andorre, ...). Les quatre informations doivent être renseignées pour être ajoutées au fichier SEPA.
(*): Depuis le
20 novembre 2016, la norme SEPA (Single European Payments Area) à évoluée et les séquences FIRST sont devenues optionnelles.
Le retour est au format JSON et se compose de cinq données:
status : « ok » ou erreur spécifiée
lignes_ajoutees : Nombre de lignes ajoutées par cette action (uniquement disponible si le status est « ok ») Donnée disponible à des fins de contrôle.
montant_ajoute : Montant ajouté par cette action (uniquement disponible si le status est « ok ») Donnée disponible à des fins de contrôle.
lignes_total : Nombre de lignes ajoutées au total (uniquement disponible si le status est « ok »). Donnée disponible à des fins de contrôle.
montant_total : Montant ajouté au total (uniquement disponible si le status est « ok ») Donnée disponible à des fins de contrôle.
Exemple d'ajout de ligne en PHP:
$iban = "Votre clé de licence";
$transaction = "identifiant de transaction retourné par l'appel à l'API start";
$return = file_get_contents( "https://www.sepawin.com/api/?a=add&i=".$iban."&t=".$transaction."&m=123,45&d=FR0000000000000000000000000&b=CMCIFR2A&n=nom&l=libelle" );
$return = json_decode($return);
if( is_object($return) && $return->statut=="ok" )
{
// Ok
print_r( $return );
}
Affiche :
stdClass Object
(
[statut] => ok
[lignes_ajoutees] => 1
[montant_ajoute] => 123.45
[lignes_total] => 1
[montant_total] => 123.45
)
Génération du résultat
Appeler l'url « https://www.sepawin.com/api/ » avec les arguments GET suivants:
a : « create »
i : Votre IBAN (qui constitue la clé de licence SepaWin)
t : Identifiant de transaction : Valeur retournée par l'appel API « start »
o : Format de sortie : « buffer » ou « file »
li : (option) Forçage du type de prélèvement (balise LclInstrm). Valeur par défaut CORE
Le retour est au format JSON et se compose de deux données:
status : « ok » ou erreur spécifiée
buffer : Contenu XML au format SEPA
ou
file : Url d'accès au fichier SEPA généré
Exemple de génération de fichier en PHP:
$iban = "Votre clé de licence";
$transaction = "identifiant de transaction retourné par l'appel à l'API start";
$return = file_get_contents( "https://www.sepawin.com/api/?a=create&i=".$iban."&t=".$transaction."&o=file" );
$return = json_decode($return);
if( is_object($return) && $return->statut=="ok" )
{
// Ok
print_r( $return );
}
Affiche :
stdClass Object
(
[statut] => ok
[file] => https://www.sepawin...xml
)
Exemple complet en PHP:
$iban = "Votre clé de licence";
$return = file_get_contents( "https://www.sepawin.com/api/?a=start&i=".$iban."&t=virement&r=ma+reference&d=06/12/2024" );
$return = json_decode($return);
if( is_object($return) && $return->statut=="ok" )
{
$transaction = $return->transaction;
$return = file_get_contents( "https://www.sepawin.com/api/?a=add&i=".$iban."&t=".$transaction."&m=123&d=FR0000000000000000000000000&b=CMCIFR2A&n=nom&l=libelle" );
$return = file_get_contents( "https://www.sepawin.com/api/?a=add&i=".$iban."&t=".$transaction."&m=456&d=FR0000000000000000000000000&b=CMCIFR2A&n=nom&l=libelle" );
$return = file_get_contents( "https://www.sepawin.com/api/?a=add&i=".$iban."&t=".$transaction."&m=789&d=FR0000000000000000000000000&b=CMCIFR2A&n=nom&l=libelle" );
$return = file_get_contents( "https://www.sepawin.com/api/?a=create&i=".$iban."&t=".$transaction."&o=file" );
$return = json_decode($return);
if( is_object($return) && $return->statut=="ok" )
{
// Ok
print_r( $return );
}
}
Affiche :
stdClass Object
(
[statut] => ok
[file] => https://www.sepawin...xml
)
suite » tester