Descripción general de la API

Esta sección detalla las API de D1 Transit, que el Emisor de Tránsito necesita implementar y las diferentes secciones para la integración backend a backend.

Diseño de la API

Formato de datos

Los datos intercambiados entre D1 Transit y los servidores del Emisor de Tránsito se formatearán como una estructura de datos JSON.

La codificación de cadenas es UTF-8 a menos que se especifique lo contrario.

Protocolo de transporte

El protocolo de comunicación utilizado para todas las interfaces será HTTPS.

Gestión de errores

Todas las respuestas de las API deben devolverse con el código de estado HTTP 200 y un código de estado aplicativo (ver lista abajo).

En caso de error inesperado del servidor (p. ej., excepción no capturada), se debe devolver el código de estado HTTP 500. En este caso, el error se considera no reintentable.

En caso de indisponibilidad del servidor, se debe devolver el código de estado HTTP 503. En este caso, el error se considera reintentable.

La tabla siguiente enumera todos los códigos de estado que se pueden usar.

Código de estado	Descripción	API aplicable
0	OK	Todas
111	Falta parámetro obligatorio	Todas
112	Formato de parámetro incorrecto	Todas
113	Emisor desconocido	Todas
116	Cuenta de tarjeta desconocida	cancelCardAccount manageDigitalCard getCardAccountInfo
117	Dispositivo desconocido
118	Sesión desconocida
119	Tarjeta digital desconocida	manageDigitalCard getDigitalCardBundleData
120	Compra desconocida
158	Tarjeta caducada	purchaseProducts getDigitalCardBundleCommands
159	Tarjeta suspendida/inactiva/lista negra	purchaseProducts getDigitalCardBundleCommands
160	La tarjeta está eliminada
162	La tarjeta tiene saldo insuficiente	purchaseProducts getDigitalCardBundleCommands
163	Cuenta de tarjeta no elegible	getDigitalCardBundleData getDigitalCardBundleCommands
164	Límite de provisión excedido	getDigitalCardBundleData
166	Información de tarjeta inválida
167	La tarjeta ya está aprovisionada	getDigitalCardBundleCommands
169	Orden de compra rechazada	purchaseProducts
170	Solicitud de aprovisionamiento rechazada	getDigitalCardBundleData
171	Incompatibilidad de cuenta de monedero. La cuenta del monedero ya está asociada con una tarjeta bajo un nombre de cliente diferente	getDigitalCardBundleData
172	código de sistema no compatible	getDigitalCardBundleCommands
173	servicio no compatible	getDigitalCardBundleCommands
177	datos de área inválidos	getDigitalCardBundleCommands
178	el estado de la tarjeta está en estación	getDigitalCardBundleCommands
192	Intento en modo lector excedió el umbral permitido	getDigitalCardBundleCommands
221	Dispositivo o servidor del monedero no accesible
231	Error inesperado del dispositivo
232	Error de memoria insuficiente del dispositivo
321	Operación ya en curso para este dispositivo	manageDigitalCard
322	Tiempo de vida de la operación expirado
419	PIN requerido	purchaseProducts
420	PIN incorrecto	purchaseProducts
421	PIN bloqueado	purchaseProducts
431	Datos de personalización inválidos
432	La operación no está permitida con el estado actual de la tarjeta	manageDigitalCard
911	La operación falló	Todas
921	Error inesperado del servidor	Todas

Los códigos de estado aplicables se describen en cada método de la API con el mejor esfuerzo.

Reglas de compatibilidad hacia atrás

Esta sección define las reglas de compatibilidad hacia atrás aplicadas por Thales para garantizar la compatibilidad con la evolución de la API.

• Thales puede añadir parámetros opcionales (en encabezado HTTP, URL y cuerpo) en las solicitudes y/o respuestas de la API. El Emisor de Tránsito no debe realizar validación estricta.

'Validación estricta' es una configuración que restringe o limita las llamadas a la API con parámetros no deseados que no están definidos en la Especificación de la API en un momento dado.

• Las cadenas de mensajes de error de la API pueden evolucionar con nuevas versiones sin ningún impacto. Estos mensajes de error son para fines de resolución de problemas y el emisor no debe esperar un formato predefinido y fijo.
• Los parámetros de solicitud o respuesta HTTP enviados por la solución D1 Transit al sistema del Emisor de Tránsito podrían cambiar de opcionales a obligatorios.
• Los parámetros de solicitud o respuesta HTTP enviados por el sistema del Emisor de Tránsito a la solución D1 Transit podrían cambiar de obligatorios a opcionales.
• El orden de los parámetros de la API no está fijado.
• Thales puede añadir nuevos valores en parámetros de enumeración existentes.
• Thales puede ampliar la API añadiendo nuevas operaciones (métodos HTTP, URL, recursos).
• Thales puede ampliar las respuestas añadiendo nuevos códigos de estado HTTP.

Fin de vida útil de parámetro/operación de la API

Thales informará al Emisor de Tránsito a más tardar nueve (9) meses antes del fin de vida, el período de desaprobación, de cualquier parámetro de la API u operación de la API (métodos HTTP, URL, recursos).

Para mayor claridad, después del período de desaprobación, los parámetros de API y las operaciones de API desaprobados no deberán ser utilizados por ningún sistema del Emisor de Tránsito en Producción y no Producción.

Thales puede acortar el período de desaprobación, sin limitación a las siguientes condiciones: (i) un riesgo significativo de seguridad; (ii) un impacto técnico material o económico sustancial; (iii) según lo requiera la Ley aplicable o los monederos digitales.

Integración de backend

Para llamar a las API de D1 Transit, se requiere la siguiente configuración:

1. Conectividad
2. Cifrado de datos

API de Transit

A continuación encontrará la lista de API disponibles

• API entrante
• API entrante de notificaciones
• API saliente

Todas las actualizaciones y evoluciones realizadas en las API de tránsito se reflejarán en las Notas de la versión

Preparación de datos

La sección de Preparación de datos a continuación proporciona información sobre los datos requeridos que el Emisor de Tránsito debe proporcionar a D1 Transit para preparar los paquetes de tarjetas digitales.