> For the complete documentation index, see [llms.txt](https://docs.payments.thalescloud.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payments.thalescloud.io/transit-digitization/es/integrar-la-api-de-d1-transit/descripcion-general-de-la-api.md).
# 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.
{% hint style="info" %}
'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.
{% endhint %}
* 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.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.payments.thalescloud.io/transit-digitization/es/integrar-la-api-de-d1-transit/descripcion-general-de-la-api.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.