GenerateSEPA: Documentación Técnica de la API

Normalmente no partes de cero. Ya tienes los datos de pago en un ERP, una herramienta contable, un export CSV o un flujo heredado en formato AEB. El problema empieza cuando esos datos tienen que convertirse en un XML SEPA válido sin limpieza manual, sin rechazos bancarios repetidos y sin que el equipo de finanzas pregunte por qué un campo que parecía opcional resulta ser obligatorio.

Ahí es precisamente donde la documentación técnica de la API suele fallar. Te dice qué endpoint acepta un payload, pero no explica por qué una referencia de mandato que falta importa, por qué el tipo de secuencia cambia el significado de un adeudo directo, o por qué un IBAN que parece válido puede provocar cargos por rechazo bancario. En los flujos financieros, la sintaxis es solo la mitad del trabajo.

Una buena documentación técnica de la API tiene que conectar el cuerpo de la solicitud con el evento de negocio. Una documentación clara e interactiva puede reducir el tiempo de incorporación hasta un 50% y el volumen de tickets de soporte entre un 30 y un 40%. En la práctica, eso significa menos ciclos de prueba fallidos y menos conversaciones entre desarrolladores y administradores de finanzas intentando descifrar lo que la API “realmente quiere.”

Introducción y primeros pasos

La generación manual de ficheros SEPA suele romperse en los mismos lugares de siempre. Un export tiene el formato de fecha incorrecto. Una cuenta acreedora es válida internamente pero no lo es para el banco. Un usuario de finanzas introduce el concepto de pago tal como aparece en la factura, pero el fichero bancario espera una estructura más estricta. Cuando esos problemas se gestionan con ediciones en hojas de cálculo e inspección de XML de última hora, el proceso se vuelve lento y frágil.

El enfoque de la API es más sencillo. Tu sistema envía JSON, el servicio valida los datos y el resultado es un fichero XML SEPA listo para el banco, ya sea para adeudos directos o transferencias de crédito. Esto elimina el paso en el que alguien tiene que transformar manualmente los datos operativos en una estructura XML que la mayoría de usuarios de negocio nunca debería tener que tocar.

Para qué sirve la API

En términos prácticos, la API realiza tres funciones:

• Recepción de datos: tu aplicación envía los datos de remesa en JSON.
• Transformación orientada al cumplimiento: el servicio mapea esos datos a la estructura SEPA correcta.
• Entrega del fichero: tu sistema recibe acceso al XML generado para entregarlo al flujo bancario.

Tu primer paso obligatorio

La autenticación va primero. El acceso se controla con una clave de API, que obtienes desde el panel de tu cuenta.

Regla práctica: Trata la clave de API como credencial de producción desde el primer día, incluso durante las pruebas. La mayoría de los problemas de integración comienzan porque los equipos tratan la primera clave de prueba como si fuera desechable y luego copian los mismos hábitos en producción.

URL base y mentalidad para la primera llamada

Usa una única URL base para todas las solicitudes:

https://api.generatesepa.com

Tu primera llamada exitosa debería apuntar a un resultado concreto: enviar una remesa mínima pero válida y confirmar que recibes una respuesta de creación junto con una ruta de recuperación del fichero. No empieces modelando todos los casos extremos de tu ERP. Empieza con un acreedor, un deudor, un importe, una fecha de ejecución y un concepto de remesa claro.

Conceptos fundamentales y flujo de trabajo de la API

Los equipos a menudo creen que están integrando un generador de ficheros. No es así. Están integrando un flujo de trabajo de pagos con supuestos regulatorios y bancarios incorporados. Esa diferencia importa porque un campo JSON solo tiene sentido cuando conoces la responsabilidad financiera que representa.

El análisis reciente indica que el 65% de los fallos de implementación en APIs financieras se deben a que personas sin perfil técnico malinterpretan el propósito de negocio de la API, no su sintaxis, razón por la que la documentación orientada al contexto de negocio resulta imprescindible en este ámbito.

El objeto remesa

El objeto central es la remesa. Piensa en ella como el contenedor de negocio para un lote de transacciones que pertenecen juntas operativa y financieramente. Una remesa no es solo un array de pagos. Lleva el contexto que le dice al banco quién inicia la domiciliación o la transferencia, bajo qué identificadores y bajo qué reglas.

Una remesa típica contiene:

• Datos del acreedor o emisor: la entidad legal que inicia la transferencia o la domiciliación.
• Contexto de ejecución: cuándo debe procesar el banco la remesa.
• Líneas de transacción: los deudores o destinatarios individuales.
• Identificadores de esquema: campos que conectan la solicitud con los requisitos específicos de SEPA.

Por qué existen los campos SEPA

Varios campos generan confusión porque parecen administrativos en lugar de técnicos. En la práctica no son opcionales.

• Identificador de acreedor: identifica a la parte que realiza domiciliaciones. Sin él, una instrucción de adeudo puede estar estructuralmente incompleta para el caso de uso previsto.
• Identificador de mandato: vincula el adeudo a la autorización firmada por el deudor.
• Tipo de secuencia: valores como FRST y RCUR le dicen al banco si el adeudo es el primero de una serie de mandatos o una domiciliación recurrente. Elegir el incorrecto no es un error de formato. Cambia el significado legal de la instrucción de pago.

El flujo de trabajo en la práctica

El flujo de trabajo real es sencillo una vez que separas los pasos:

1. Tu sistema envía JSON con los metadatos de remesa y las líneas de transacción.
2. La API valida los campos críticos de negocio como identificadores, formatos de fecha y datos de cuenta.
3. El servicio convierte la solicitud en XML SEPA con la estructura adecuada para el tipo de remesa.
4. Tu sistema recibe un resultado que confirma el procesamiento y proporciona acceso al fichero generado.
5. El proceso financiero continúa con la descarga, revisión si es necesaria, y envío al banco.

Una integración limpia ocurre cuando los desarrolladores y los responsables de finanzas pueden responder a la misma pregunta: ¿qué evento de negocio representa este payload?

Autenticación y protocolos de seguridad

La autenticación en la API usa el esquema Bearer en la cabecera Authorization. Mantenlo claro y predecible. Si la cabecera es incorrecta, el resto de la solicitud es irrelevante.

Formato de la cabecera

Usa exactamente este patrón:

Authorization: Bearer TU_CLAVE_API

Un ejemplo HTTP mínimo:

POST /v1/remittances HTTP/1.1
Host: api.generatesepa.com
Authorization: Bearer TU_CLAVE_API
Content-Type: application/json

Cómo almacenar la clave

Guardar la clave directamente en el código fuente es la manera más rápida de crear un problema de limpieza posterior. Almacénala en una variable de entorno y léela en tiempo de ejecución desde la configuración de tu aplicación.

Manejo recomendado:

• Desarrollo local: mantén la clave en un fichero de entorno local que no se suba al repositorio.
• Entornos compartidos: inyecta la clave a través del gestor de secretos de tu plataforma de despliegue.
• Rotaciones: diseña tu aplicación para que la clave pueda reemplazarse sin cambios de código.
• Logs: nunca imprimas la clave completa en logs de aplicación, trazas de excepciones o capturas de pantalla de soporte.

Modelo de seguridad alrededor de la solicitud

Todos los datos en tránsito están cifrados con TLS 1.2+. Los datos de remesas de clientes se eliminan automáticamente de los servidores 10 minutos después del procesamiento. Por eso tu integración debe recuperar el output rápidamente en lugar de asumir que seguirá disponible indefinidamente.

Cómo son las integraciones seguras en producción

Una integración segura suele tener tres características:

• Credenciales de propósito único: una clave por entorno, no una clave copiada en todo.
• Ruta corta desde la solicitud hasta la recuperación: envía, confirma, descarga y almacena el fichero resultante en tu propio sistema controlado.
• Sin filtraciones de credenciales en los bucles de soporte: cuando falle una integración, registra IDs de solicitud y errores de validación, no secretos.

Referencia del endpoint: creación de remesas

El endpoint principal para la generación de ficheros es:

POST /v1/remittances

Este endpoint acepta un payload JSON que describe la remesa y devuelve una respuesta de creación cuando la solicitud supera la validación y el XML se genera correctamente.

Ejemplo del cuerpo de la solicitud

{
  "type": "direct_debit",
  "execution_date": "2026-06-30",
  "creditor_name": "Acme Services S.L.",
  "creditor_iban": "ES9121000418450200051332",
  "creditor_id": "ES98ZZZ123456789",
  "currency": "EUR",
  "sequence_type": "FRST",
  "transactions": [
    {
      "debtor_name": "Laura Martin",
      "debtor_iban": "ES7921000813610123456789",
      "amount": 125.50,
      "concept": "Factura INV-2026-0042",
      "mandate_id": "MANDATO-00045",
      "mandate_signature_date": "2025-12-15",
      "end_to_end_id": "INV-2026-0042"
    }
  ]
}

Referencia de campos

Campo	Tipo	Obligatorio	Descripción
type	string	Sí	Tipo de remesa: adeudo directo o transferencia de crédito
execution_date	string	Sí	Fecha de procesamiento en formato ISO 8601
creditor_name	string	Sí	Nombre legal o comercial de la parte iniciadora
creditor_iban	string	Sí	IBAN de la cuenta que envía o recibe los fondos
creditor_id	string	Obligatorio para adeudo directo	Identificador de acreedor SEPA
currency	string	Sí	Código de moneda. Usa EUR para remesas SEPA
sequence_type	string	Obligatorio para adeudo directo	Secuencia del adeudo: FRST o RCUR
transactions	array	Sí	Lista de instrucciones de pago o adeudo

Reglas de validación importantes

• Las fechas deben usar ISO 8601. Usa YYYY-MM-DD. No envíes fechas en formato local como 30/06/2026.
• Los valores IBAN se validan por estructura de código de país, longitud esperada y lógica de suma de verificación.
• El texto del concepto debe ser conciso y apropiado para el banco. No lo trates como un campo de notas libre.
• El tipo de secuencia debe coincidir con el estado del mandato. FRST y RCUR no son etiquetas intercambiables.

Mapeo de formatos AEB heredados

Si tus datos de origen provienen de ficheros bancarios españoles antiguos, la capa de API debe convertirse en tu punto de traducción. Los imports heredados típicos como AEB 34, 14 y 59 deben mapearse a la estructura JSON de remesa antes de su envío.

Comprensión de las respuestas de la API

Una solicitud de creación exitosa devuelve 201 Created y un cuerpo JSON con la información que tu aplicación necesita para continuar el flujo de trabajo.

Ejemplo de respuesta exitosa

{
  "remittance_id": "rem_8f3c2a91",
  "status": "completed",
  "download_url": "https://api.generatesepa.com/downloads/rem_8f3c2a91.xml",
  "expires_at": "2026-06-25T10:25:00Z"
}

Campo	Significado	Cómo usarlo
remittance_id	Identificador único de la remesa generada	Guárdalo en logs, registros de conciliación y tickets de soporte
status	Resultado del procesamiento	Confirma que el XML está listo antes de intentar la recuperación
download_url	Enlace seguro temporal al fichero generado	Descarga el XML inmediatamente y guárdalo en tu sistema
expires_at	Tiempo de expiración del acceso al fichero	Úsalo para evitar intentar recuperar un artefacto caducado

La URL expira después de 10 minutos. Recupera el XML inmediatamente después de recibir la respuesta 201 Created.

Recupera primero, concilia después. Si inviertes ese orden, una remesa válida puede convertirse en un fallo de recuperación evitable.

Gestión de errores y códigos de referencia

Los errores deben ayudar al llamante a recuperarse. La estructura estándar incluye un código de estado HTTP más un error_code legible por máquina y un error_message legible por personas.

Formato estándar de error

{
  "error_code": "INVALID_IBAN",
  "error_message": "El campo debtor_iban no superó la validación de IBAN.",
  "details": {
    "field": "transactions[0].debtor_iban"
  }
}

Referencia de códigos de error de la API

Estado HTTP	Código de error	Descripción	Acción sugerida
400	INVALID_REQUEST	Cuerpo malformado o campos obligatorios ausentes	Valida la estructura JSON y los campos obligatorios antes de reenviar
400	INVALID_IBAN	Un campo IBAN no superó la validación	Comprueba el código de país, la longitud y la suma de verificación
400	INVALID_DATE_FORMAT	Un campo de fecha no usa el formato esperado	Envía fechas en formato ISO 8601: YYYY-MM-DD
400	INVALID_SEQUENCE_TYPE	El tipo de secuencia es incompatible con el contexto	Confirma si el mandato debe ser primero o recurrente
401	UNAUTHORIZED	Clave de API ausente, caducada o inválida	Verifica la cabecera Authorization: Bearer y el origen de la clave
429	RATE_LIMITED	Demasiadas solicitudes en poco tiempo	Reduce la tasa y reintenta con política de espera exponencial
500	INTERNAL_ERROR	El servicio falló al procesar una solicitud válida	Reintenta si procede y registra el contexto de la solicitud para soporte

Ejemplos prácticos de integración

Ejemplo con cURL

curl -X POST "https://api.generatesepa.com/v1/remittances" \
  -H "Authorization: Bearer $GENERATESEPA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "direct_debit",
    "execution_date": "2026-06-30",
    "creditor_name": "Acme Services S.L.",
    "creditor_iban": "ES9121000418450200051332",
    "creditor_id": "ES98ZZZ123456789",
    "currency": "EUR",
    "sequence_type": "FRST",
    "transactions": [
      {
        "debtor_name": "Laura Martin",
        "debtor_iban": "ES7921000813610123456789",
        "amount": 125.50,
        "concept": "Factura INV-2026-0042",
        "mandate_id": "MANDATO-00045",
        "mandate_signature_date": "2025-12-15",
        "end_to_end_id": "INV-2026-0042"
      }
    ]
  }'

Ejemplo en JavaScript

import axios from "axios";

const apiKey = process.env.GENERATESEPA_API_KEY;

const payload = {
  type: "direct_debit",
  execution_date: "2026-06-30",
  creditor_name: "Acme Services S.L.",
  creditor_iban: "ES9121000418450200051332",
  creditor_id: "ES98ZZZ123456789",
  currency: "EUR",
  sequence_type: "FRST",
  transactions: [
    {
      debtor_name: "Laura Martin",
      debtor_iban: "ES7921000813610123456789",
      amount: 125.5,
      concept: "Factura INV-2026-0042",
      mandate_id: "MANDATO-00045",
      mandate_signature_date: "2025-12-15",
      end_to_end_id: "INV-2026-0042"
    }
  ]
};

async function crearRemesa() {
  try {
    const response = await axios.post(
      "https://api.generatesepa.com/v1/remittances",
      payload,
      {
        headers: {
          Authorization: `Bearer ${apiKey}`,
          "Content-Type": "application/json"
        }
      }
    );
    console.log("Remesa creada:", response.data.remittance_id);
    console.log("Estado:", response.data.status);
    console.log("URL de descarga:", response.data.download_url);
  } catch (error) {
    if (error.response) {
      console.error("Estado HTTP:", error.response.status);
      console.error("Código de error:", error.response.data.error_code);
      console.error("Mensaje:", error.response.data.error_message);
    } else {
      console.error("Solicitud fallida:", error.message);
    }
  }
}

crearRemesa();

Ejemplo en Python

import os
import requests

api_key = os.environ.get("GENERATESEPA_API_KEY")

payload = {
    "type": "direct_debit",
    "execution_date": "2026-06-30",
    "creditor_name": "Acme Services S.L.",
    "creditor_iban": "ES9121000418450200051332",
    "creditor_id": "ES98ZZZ123456789",
    "currency": "EUR",
    "sequence_type": "FRST",
    "transactions": [
        {
            "debtor_name": "Laura Martin",
            "debtor_iban": "ES7921000813610123456789",
            "amount": 125.50,
            "concept": "Factura INV-2026-0042",
            "mandate_id": "MANDATO-00045",
            "mandate_signature_date": "2025-12-15",
            "end_to_end_id": "INV-2026-0042"
        }
    ]
}

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

response = requests.post(
    "https://api.generatesepa.com/v1/remittances",
    json=payload,
    headers=headers,
    timeout=30
)

if response.status_code == 201:
    data = response.json()
    print("Remesa creada:", data["remittance_id"])
    print("Estado:", data["status"])
    print("URL de descarga:", data["download_url"])
else:
    try:
        error = response.json()
        print("Estado HTTP:", response.status_code)
        print("Código de error:", error.get("error_code"))
        print("Mensaje:", error.get("error_message"))
    except ValueError:
        print("Estado HTTP:", response.status_code)
        print("Respuesta de error no JSON:", response.text)

Límites de tasa, SLA y buenas prácticas

La plataforma ofrece una disponibilidad del 99,9% y utiliza un modelo de API versionado bajo /v1/, lo que proporciona a los clientes un objetivo de integración estable.

Hábitos de producción que reducen el trabajo de soporte

• Respeta los límites de tasa: tu cliente debe reconocer las respuestas 429 y reintentar con espaciado en lugar de saturar el endpoint.
• Diseña para idempotencia en tu lado: si tu gestor de trabajos reintenta tras un timeout, asegúrate de poder detectar si la remesa ya fue creada.
• Almacena datos de correlación: mantén tu propio ID de lote vinculado al remittance_id devuelto.
• Revisa los changelogs antes de los despliegues: las APIs versionadas solo son útiles si tu proceso de release comprueba qué ha cambiado.

La estabilidad viene de la coherencia. Las mismas reglas de payload, las mismas reglas de logging y las mismas reglas de reintento deben aplicarse en cada entorno.

---

Si quieres dejar de construir ficheros SEPA a mano y pasar a un flujo de trabajo validado de JSON a XML, ConversorSEPA ofrece a los equipos técnicos y a los departamentos de finanzas una forma práctica de automatizar remesas, soportar formatos bancarios heredados y producir XML SEPA listo para el banco sin tener que mantener la lógica de conversión internamente.

---

Preguntas frecuentes

¿Para qué sirve la API de GenerateSEPA?

La API de GenerateSEPA acepta un payload JSON que describe una remesa, valida los datos según las reglas SEPA y devuelve un fichero XML SEPA listo para el banco. Gestiona tanto adeudos directos como transferencias de crédito, eliminando la necesidad de construir o inspeccionar XML manualmente.

¿Cómo me autentico con la API de GenerateSEPA?

La autenticación usa el esquema Bearer en la cabecera Authorization: Authorization: Bearer TU_CLAVE_API. Obtén la clave desde el panel de tu cuenta y guárdala en una variable de entorno, nunca en el código fuente. Trata la clave como credencial de producción desde el primer día de integración, incluso durante las pruebas.

¿Cuáles son los campos SEPA más importantes en la solicitud a la API?

Para adeudos directos, los campos obligatorios más allá de los datos básicos de acreedor y transacción son creditor_id (el identificador de acreedor SEPA), mandate_id (que vincula el adeudo a una autorización firmada) y sequence_type (FRST para el primer adeudo, RCUR para recurrentes). Usar valores incorrectos cambia el significado legal de la instrucción de pago, no solo su formato.

¿Cuánto tiempo está disponible el fichero XML SEPA generado tras la creación?

La URL de descarga expira tras 10 minutos y los datos de remesas de clientes se eliminan automáticamente de los servidores tras el procesamiento. Recupera el XML inmediatamente después de recibir la respuesta 201 Created y guárdalo en tu propio sistema seguro. No construyas integraciones que dependan de reabrir enlaces de descarga antiguos desde logs históricos.

---

Artículos relacionados