> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK de servidor: Python, Node, Go, Java, PHP, Ruby, .NET

> Didit ofrece SDK oficiales tipados para llamar a sus API desde tu backend: instalación, configuración, errores, reintentos, versionado y soporte.

Los SDK de servidor son las bibliotecas oficiales de Didit para tu backend. Cada uno invoca los endpoints de servidor de la [referencia de la API](https://docs.didit.me/es/api-reference/overview.md) con solicitudes y respuestas tipadas, verifica los webhooks que Didit te envía y comprueba los tokens de [Didit Authentication](https://docs.didit.me/es/authentication/overview.md). Ninguna versión 1.0.1 incluye todavía los dos endpoints de Google Wallet: [iniciar una verificación con Google Wallet](https://docs.didit.me/es/api-reference/digital-id-wallets/google-wallet.md) y [enviar una respuesta de la wallet](https://docs.didit.me/es/standalone-apis/digital-id-wallet-response.md). Los SDK de Python, Node.js, Java, PHP, Ruby y .NET incluyen todos los demás endpoints de servidor. A Go 1.0.1 le faltan además otros nueve, la mayoría son endpoints de Travel Rule: consulta [Endpoints que aún no están en el SDK de Go](https://docs.didit.me/es/integration/server-sdks/go.md#endpoints-que-aún-no-están-en-el-sdk-de-go).

Úsalos en cualquier parte de tu código que tenga una clave de API de Didit: para crear sesiones de verificación, leer decisiones, llamar a las API independientes, gestionar usuarios, empresas, flujos de verificación (workflows) y casos, analizar transacciones y wallets, y para la Travel Rule. En el navegador o en una aplicación móvil, usa en su lugar los SDK [web](https://docs.didit.me/es/integration/web-sdks/overview.md) y [nativos](https://docs.didit.me/es/integration/native-sdks/overview.md): presentan el flujo de verificación a tu usuario y nunca tienen tu clave de API.

Las páginas de los endpoints de servidor de la [referencia de la API](https://docs.didit.me/es/api-reference/overview.md), incluidas las páginas de los servicios de [Validación de base de datos](https://docs.didit.me/es/standalone-apis/database-validation.md), muestran un ejemplo de código para cada SDK de servidor junto a la solicitud cURL. Se muestra un ejemplo cuando la última versión del SDK incluye el endpoint y todos los campos que envía el ejemplo: un endpoint o un campo que se añade a la API tendrá ejemplos en la siguiente versión de cada SDK. Ninguna versión 1.0.1 incluye los 16 campos de solicitud de Validación de base de datos que se añadieron después de generarla, como `vin` o `bank_account_number`, así que las páginas de los servicios cuyas solicitudes incluyen esos campos solo muestran cURL.

## Instalación

```bash Python theme={null}
pip install didit-sdk
```

```bash Node.js theme={null}
npm install @didit-protocol/sdk-node
```

```bash Go theme={null}
go get github.com/didit-protocol/sdk-go
```

```kotlin Java theme={null}
implementation("me.didit:didit-java:1.0.1")
```

```bash PHP theme={null}
composer require didit-protocol/sdk-php guzzlehttp/guzzle
```

```bash Ruby theme={null}
gem install didit-sdk
```

```bash .NET theme={null}
dotnet add package Didit
```

| Lenguaje | Paquete | Código fuente | Entorno de ejecución mínimo |
| - | - | - | - |
| [Python](https://docs.didit.me/es/integration/server-sdks/python.md) | [PyPI `didit-sdk`](https://pypi.org/project/didit-sdk/) | [sdk-python](https://github.com/didit-protocol/sdk-python) | Python 3.10 |
| [Node.js y TypeScript](https://docs.didit.me/es/integration/server-sdks/node.md) | [npm `@didit-protocol/sdk-node`](https://www.npmjs.com/package/@didit-protocol/sdk-node) | [sdk-node](https://github.com/didit-protocol/sdk-node) | Node.js 18, Bun, Deno, entornos edge con `fetch` |
| [Go](https://docs.didit.me/es/integration/server-sdks/go.md) | [Módulo de Go `github.com/didit-protocol/sdk-go`](https://pkg.go.dev/github.com/didit-protocol/sdk-go) | [sdk-go](https://github.com/didit-protocol/sdk-go) | Go 1.22 |
| [Java y Kotlin](https://docs.didit.me/es/integration/server-sdks/java.md) | [Maven Central `me.didit:didit-java`](https://central.sonatype.com/artifact/me.didit/didit-java) | [sdk-java](https://github.com/didit-protocol/sdk-java) | Java 11 |
| [PHP](https://docs.didit.me/es/integration/server-sdks/php.md) | [Packagist `didit-protocol/sdk-php`](https://packagist.org/packages/didit-protocol/sdk-php) | [sdk-php](https://github.com/didit-protocol/sdk-php) | PHP 8.1 |
| [Ruby](https://docs.didit.me/es/integration/server-sdks/ruby.md) | [RubyGems `didit-sdk`](https://rubygems.org/gems/didit-sdk) | [sdk-ruby](https://github.com/didit-protocol/sdk-ruby) | Ruby 3.1 |
| [C# y .NET](https://docs.didit.me/es/integration/server-sdks/dotnet.md) | [NuGet `Didit`](https://www.nuget.org/packages/Didit) | [sdk-dotnet](https://github.com/didit-protocol/sdk-dotnet) | .NET 8 o .NET Standard 2.0 |

## Configuración

Todos los SDK leen las mismas variables de entorno, así que un cliente creado sin opciones está listo para usarse. Los entornos edge no tienen variables de entorno de proceso: en ellos, pasa la clave de API al cliente de Node.js como opción.

| Variable | Uso |
| - | - |
| `DIDIT_API_KEY` | Cada llamada con clave de API. Crea la clave en la consola, en [Claves de API](https://docs.didit.me/es/console/api-keys.md). |
| `DIDIT_ORGANIZATION_ID`, `DIDIT_APPLICATION_ID` | Operaciones bajo `/v3/organization/{organization_id}/application/{application_id}/` (casos, redes, informes regulatorios, plantillas de informes y algunas herramientas de usuarios y empresas). El SDK rellena ambos ID de ruta a partir del cliente, así que nunca los pasas en cada llamada. Sin ellos, esas llamadas fallan antes de enviar ninguna solicitud. |
| `DIDIT_LOG=debug` | Registra el método, la ruta, el estado, la duración y el id de solicitud de cada solicitud. Los cuerpos y los encabezados nunca se registran. |

Todo lo que puedes configurar mediante el entorno también puedes pasarlo al cliente, junto con la URL base, el tiempo de espera, los reintentos, los encabezados predeterminados y tu propio cliente HTTP. Crea un cliente por proceso y compártelo: mantiene un pool de conexiones y es seguro usarlo desde varios hilos o tareas.

Los métodos de `account` ([registro programático](https://docs.didit.me/es/integration/programmatic-registration.md): registro, inicio de sesión, organizaciones y aplicaciones) invocan el endpoint `https://apx.didit.me/auth/v2` y nunca envían tu clave de API. Inicia sesión con `account.login` y, después, pasa el token de acceso devuelto al cliente como su token de cuenta.

## Qué hace cada SDK

* **Recursos y métodos.** Las llamadas siguen los recursos de la API: `client.<resource>.<method>(...)`, por ejemplo `sessions.create`, `sessions.retrieve_decision` o `transactions.create`, con la convención de mayúsculas y minúsculas de cada lenguaje. Los id de la ruta son argumentos posicionales; el cuerpo y la consulta son un único conjunto de campos con nombre. Python, Node.js, PHP y Ruby usan los nombres de campo de la propia API (`workflow_id`); Go, Java y .NET usan la convención de su lenguaje (`WorkflowID`, `workflowId`, `WorkflowId`).
* **Listas.** Los métodos de listado recorren todos los resultados por ti (con `limit` y `offset` internamente) y además exponen cada página con `count`, `next`, `previous` y `results`. En Ruby, `auto_paging_each` recorre todas las páginas, y los `total_count`, `next_url` y `previous_url` de una página son los `count`, `next` y `previous` de la API.
* **Archivos.** Las subidas (imágenes de documentos, selfies, prueba de domicilio, importaciones) aceptan una ruta, bytes o un stream. Las descargas (PDF de sesiones, informes) devuelven bytes o un stream, nunca JSON analizado.
* **Compatibilidad futura.** Un campo de respuesta o un valor de enum que la versión del SDK aún no conoce se conserva y se puede leer, nunca produce un error, así que una incorporación a la API no rompe una integración ya desplegada.
* **Webhooks.** `webhooks.verify` comprueba los encabezados `X-Signature-V2` y `X-Signature` y la marca de tiempo de una entrega con tu secreto de webhook, y devuelve un evento tipado. Acepta una lista de secretos mientras rotas uno. Consulta [Webhooks](https://docs.didit.me/es/integration/webhooks.md) para conocer el esquema de firma.
* **Authentication.** Un helper `Authentication` verifica los tokens de acceso y de ID que firma tu emisor de Authentication, e invoca sus endpoints de token, de sesión y de step-up. Nunca usa tu clave de API.

## Errores, reintentos y tiempos de espera

| Error | Cuándo |
| - | - |
| `APIConnectionError`, `APITimeoutError` | No llegó ninguna respuesta |
| `APIStatusError` | Cualquier otra respuesta que no sea 2xx, con el estado, el cuerpo analizado, los encabezados y el ID de la solicitud |
| `BadRequestError` 400, `AuthenticationError` 401, `PermissionDeniedError` 403, `NotFoundError` 404, `ConflictError` 409, `UnprocessableEntityError` 422, `RateLimitError` 429, `InternalServerError` 5xx | Subclases de `APIStatusError` |
| `WebhookVerificationError` | Una entrega de webhook no superó la verificación; su `reason` indica el motivo |
| `ConfigurationError` | Falta la clave de API, el token de cuenta, el ID de organización o el ID de aplicación |

Todos los errores derivan de `DiditError`. En Go, todos los errores implementan la interfaz `didit.Error` y son de tipo puntero, como `*didit.NotFoundError`. Java, PHP y .NET los nombran con su sufijo habitual `Exception` y escriben `API` como `Api`: `DiditException`, `ApiStatusException`, `NotFoundException`.

Los SDK reintentan una solicitud fallida hasta 2 veces, con backoff exponencial a partir de 0,5 segundos (jitter completo, como máximo 8 segundos) y respetando `Retry-After`. `GET`, `HEAD`, `PUT` y `DELETE` se reintentan ante errores de conexión, tiempos de espera agotados, 408, 429 y 5xx. `POST` y `PATCH` solo se reintentan ante un 429 o cuando la conexión falló antes de enviar la solicitud, de modo que un reintento nunca crea una segunda sesión o transacción. El tiempo de espera predeterminado es de 60 segundos. Cada respuesta expone además el estado HTTP sin procesar, los encabezados y el ID de la solicitud. Consulta [Límite de solicitudes](https://docs.didit.me/es/integration/rate-limiting.md) para conocer los límites que hay detrás del 429.

## Versionado y soporte

* Los SDK siguen el versionado semántico. Cuando un endpoint se elimina de la API o se renombra su método, el método anterior se mantiene al menos una versión menor más, marcado como obsoleto, para que tu código siga compilando mientras migras al nuevo.
* Se generan a partir del contrato publicado de la API ([`openapi-25.json`](https://docs.didit.me/openapi-25.json) y [`openapi-auth.json`](https://docs.didit.me/openapi-auth.json)) y lo comprueban cada día, así que un nuevo endpoint o campo llega en una versión ordinaria de los siete SDK.
* Cada SDK es compatible con el runtime mínimo de la tabla y con todas las versiones posteriores. Sus pruebas se ejecutan en el mínimo y en cada versión posterior, o en cada versión de soporte a largo plazo en el caso de Node.js y Java.
* El `CHANGELOG.md` de cada repositorio enumera los cambios de cada versión.
* Informa de un problema de seguridad de forma privada mediante los avisos de seguridad del repositorio del SDK o escribiendo a [support@didit.me](mailto:support@didit.me).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.