<!-- source_url: https://docs.mynexusapi.com/v1/guias/sdk | last_updated: 2026-11-17 -->

# SDKs

Bibliotecas oficiales para .NET, Node.js, Python, Java y PHP que llaman a la API por ti y resuelven la idempotencia, los reintentos y los webhooks.

Puedes integrarte con nuestros servicios de facturación desde tu propio lenguaje
con nuestros SDK oficiales, que instalas con el gestor de paquetes que ya usas.
Trabajas con los mismos endpoints y las mismas respuestas que documentan las
guías, ya convertidas en objetos de tu lenguaje, y te despreocupas de la parte
donde más errores se cometen: reutilizar la `Idempotency-Key`, reintentar sin
duplicar comprobantes y verificar la firma de los webhooks.

En esta página comparas los cinco SDK, ves qué hacen por ti y qué endpoints
cubren, y encuentras el enlace a la guía de tu lenguaje.

## Antes de empezar

- [ ] Una API Key de pruebas. Si todavía no tienes una, crea tu sandbox como se
      explica en [Sandbox de pruebas](/v1/guias/sandbox); el alta tarda unos 10
      minutos.
- [ ] Nada que registrar para la IP en sandbox: acepta llamadas desde cualquier
      IP. En producción, la IP de salida se registra en **Cuenta > IP permitidas**
      ([como](/v1/guias/sandbox#si-tu-ip-cambia)).
- [ ] El entorno de tu lenguaje, en la versión mínima que indica la
      [Comparativa](#comparativa), con su gestor de paquetes (NuGet, npm, pip,
      Composer, Maven o Gradle).

## Comparativa

La columna **Versión** indica la versión actual de cada SDK.

| Lenguaje | Paquete | Versión mínima del lenguaje | Instalación | Versión | Registro / repositorio | Guía |
|---|---|---|---|---|---|---|
| .NET | `Ecuafact.Sdk` (+ `Ecuafact.Sdk.Core` para inyección de dependencias) | .NET Framework 4.6.1 o cualquier .NET compatible con `netstandard2.0`; probado en .NET 10 | `dotnet add package Ecuafact.Sdk` (y `dotnet add package Ecuafact.Sdk.Core` si usas inyección de dependencias) | `1.0.1` en ambos paquetes | [NuGet](https://www.nuget.org/packages/Ecuafact.Sdk) | [SDK .NET](/v1/guias/sdk-dotnet) |
| Node.js | `@ecuafact/sdk` | Node.js 18 (módulo ES) | `npm install @ecuafact/sdk` | `1.0.1` | [npm](https://www.npmjs.com/package/@ecuafact/sdk) | [SDK Node.js](/v1/guias/sdk-node) |
| Python | `ecuafact` | Python 3.10 | `pip install ecuafact` | `1.0.1` | [PyPI](https://pypi.org/project/ecuafact/) | [SDK Python](/v1/guias/sdk-python) |
| Java | `com.ecuafact:sdk` | Java 17 | Dependencia Maven/Gradle `com.ecuafact:sdk:1.0.1` | `1.0.1` | [Maven Central](https://central.sonatype.com/artifact/com.ecuafact/sdk) | [SDK Java](/v1/guias/sdk-java) |
| PHP | `ecuafact/sdk` | PHP 8.2 con `ext-curl` | `composer require ecuafact/sdk` | `v1.0.1` | [GitHub](https://github.com/Ecuanexus/ecuafact-sdk-php) / [Packagist](https://packagist.org/packages/ecuafact/sdk) | [SDK PHP](/v1/guias/sdk-php) |

## Qué hace el SDK por ti

La tabla muestra lo que puedes dejar en manos de nuestros SDK y lo que tendrías
que programar tú si consumes la API por HTTP directo.

| Tarea | Con el SDK | Por HTTP directo |
|---|---|---|
| Autenticación | Configuras la API Key una vez, o el SDK la lee de `ECUAFACT_API_KEY`. Viaja en `X-Api-Key` en cada llamada y no aparece al imprimir el cliente ni sus opciones. | Agregas la cabecera en cada petición. |
| URL base | La pasas una vez, sin `/v1`, o el SDK la lee de `ECUAFACT_BASE_URL`. El SDK no tiene una opción de ambiente; trabajas en pruebas o en producción según la URL que configuras. | Construyes cada ruta. |
| `Idempotency-Key` | Si no la pasas, el SDK genera una, la reutiliza en sus reintentos y te la devuelve. Antes de enviarla, comprueba la misma regla que aplica la API: de 1 a 128 caracteres, solo letras, dígitos y `- _ . : /`. | La generas, la guardas y la reenvías tú. |
| Reintentos | Puedes enviar sin preocuparte por los cortes de red: el SDK reintenta por ti los estados 408, 425, 500, 502, 503 y 504 y los errores de red, con 3 intentos en total por defecto, y respeta `Retry-After`. Solo reintenta operaciones idempotentes: `GET` y `POST`/`PUT` con `Idempotency-Key`; un `POST` o `PUT` sin clave, como la actualización del perfil, no se reintenta. El cambio de logo es la excepción en .NET y Python, que lo reintentan aunque no lleva clave porque subir el mismo archivo deja el perfil igual; en Node.js, Java y PHP no se reintenta. Puedes configurar los estados que se reintentan, la espera base, el backoff lineal o exponencial, la variación aleatoria y el tope de tiempo total. | Implementas la espera y el límite de intentos. |
| Límite de solicitudes y cupo | El 429 por límite de solicitudes, que trae el `codEstado` 5005 (`limite_solicitudes`), se reintenta por defecto: el SDK espera lo que indica `Retry-After` y repite la solicitud. Si prefieres manejarlo tú, desactiva `RetryRateLimited` y el SDK lanza una excepción con la espera sugerida. El cupo agotado, un 429 con el `codEstado` 4004 (`cupo_agotado`), **nunca** se reintenta. | Distingues el 5005 del 4004 leyendo `codEstado`. |
| Importes | Usa tipos exactos, como `decimal` en .NET, `BigDecimal` en Java y `Decimal` en Python; en Node.js y PHP aceptas `number` o texto decimal. Los envía como número JSON sin pérdida de precisión. | Cuidas el redondeo y el formato del número. |
| Errores | Puedes capturar una excepción por categoría (autenticación, validación, no encontrado, conflicto, límite, cupo, servidor, conexión, timeout, respuesta ilegible, respuesta demasiado grande, configuración y webhook). Si una emisión recibe una respuesta 2xx que el SDK no puede leer, la excepción conserva la `Idempotency-Key` de la solicitud y, según el lenguaje, su identificador de correlación; repite la emisión con esa misma clave y no se duplica el comprobante. Cada una trae el `codEstado` numérico, el `estado`, `msgError`, `errores` con el detalle, `estadoHttp`, `correlationId` con el valor de `X-Correlation-Id`, `idempotencyKey`, `retryAfter` y `esReintentable`. Los códigos del [catálogo](/v1/guias/errores#catalogo-de-codestado) están como constantes con nombre, por ejemplo `CodEstado.ComprobanteInvalido` (3002). | Lees el JSON de error y las cabeceras. |
| Respuestas | Recibes objetos tipados, con los mismos campos de la respuesta JSON. La emisión y el seguimiento usan la misma forma, con `codEstado`, `errores`, `numeroDocumento`, `referenciaExterna`, `fhRecibido` y `fhAutorizacion`. El `estado` llega también como enum (`EstadoOperacion`) y el `tipoDocumento` como `TipoComprobante`; un estado que el SDK no reconoce se lee como `Desconocido`, y un tipo de comprobante desconocido, como `null`. Además tienes `esFinal` y `esAutorizado`. | Interpretas el JSON y comparas texto. |
| Seguimiento | Si prefieres esperar el resultado en tu código, puedes usar el método opcional `esperarResultado`, que consulta la operación hasta un estado final o hasta un tiempo máximo. También puedes recibir el resultado por webhooks. | Escribes el bucle de consulta. |
| Webhooks | Puedes verificar `Ecuafact-Signature` o las cabeceras de Standard Webhooks sobre el cuerpo crudo (texto o bytes), con varios secretos si necesitas rotarlos, y recibes el evento tipado. | Calculas el HMAC-SHA256, comparas en tiempo constante y parseas el JSON. |
| Logo del perfil | `actualizarLogo` arma la petición `multipart/form-data` por ti. | Construyes el multipart. |
| Varios contribuyentes | Si trabajas con varios contribuyentes, `para(identificacion)` te da una vista fija por contribuyente con todos los métodos que dependen de la identificación. | Cambias la ruta en cada llamada. |
| Opciones por llamada | `RequestOptions` cambia en una sola llamada el tiempo por intento, el tope total, el `X-Correlation-Id` y los reintentos. La forma de cancelar una llamada depende del lenguaje. | Configuras cada petición. |
| Información adicional | Puedes enviar un dato tuyo en la cabecera opcional `X-Additional-Info`, en todas tus llamadas o en una sola, como se explica en [Información adicional](#informacion-adicional). | Agregas la cabecera tú. |
| Estado del servicio y catálogos | Consultas el estado público del servicio, sin API Key, y los catálogos del SRI como objetos tipados. Los nombres están en [Nombres equivalentes](#nombres-equivalentes). | Armas las peticiones y lees el JSON. |
| Armar comprobantes | Puedes usar el constructor opcional `ComprobanteBuilder`, que arma la estructura de los seis tipos con los valores que le das, sin calcular totales ni completar valores por defecto: la API calcula y valida. | Escribes el JSON. |
| Conexión | Te deja configurar el proxy, TLS y el tiempo de conexión. Cada lenguaje usa sus propias opciones, que están en la fila **Conexión** de [Nombres equivalentes](#nombres-equivalentes). | Configuras tu cliente HTTP. |

## Cuándo usar SDK o HTTP directo

Te recomendamos nuestro **SDK** si tu lenguaje está en la tabla y puedes agregar
dependencias a tu proyecto.

Te conviene consumir la API por **HTTP directo** en cualquiera de estos casos:

- Tu lenguaje no tiene SDK (Go, Ruby o Delphi, por ejemplo) o tu plataforma no
  te permite agregar paquetes.
- Necesitas un endpoint que tu SDK no cubre; la lista está en
  [Cobertura](#cobertura).
- Quieres controlar cada petición, por ejemplo para medirla con tus propias
  métricas o para reintentar de una forma que el SDK no permite configurar.

Cada guía de endpoint trae ejemplos HTTP en cURL, .NET, Python, Node.js, PHP y
Java; si eliges este camino, empieza por [Primeros pasos](/v1/guias/primeros-pasos).
Si en cambio no quieres escribir código, puedes emitir con el
[CLI de Ecuafact](/v1/guias/cli) desde la terminal o desde un script, a partir
de archivos JSON, CSV o Excel.

## Ejemplo

Este ejemplo emite una factura con cada SDK. El archivo `comprobante.json`
contiene la [Estructura del comprobante](/v1/guias/emision-01), y cada guía de
SDK lo trae completo en su quickstart. La API responde `202 Accepted` con el
`estado` `recibido`, el `codEstado` 1001 o 1002 y un `idOperacion` para hacer el
[seguimiento](/v1/guias/consulta-operacion). Con 1001 todavía no hay clave de
acceso y `claveAcceso` es `null`; con 1002 ya viene, así que tu código debe
aceptar los dos valores. Si repites la emisión con la misma
`Idempotency-Key` y el mismo cuerpo, la respuesta trae el mismo
`idOperacion` y el estado actual de la operación, y no se crea otro comprobante.

> [!IMPORTANT]
> Ambiente de pruebas: sin validez fiscal.

```csharp-sdk
using System.Text.Json;
using Ecuafact.Sdk;
using Ecuafact.Sdk.Contracts;

using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions
{
    BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"),
    ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!
});
FacturaRequest comprobante = JsonSerializer.Deserialize<FacturaRequest>(
    await File.ReadAllTextAsync("comprobante.json"))!;

EmisionResultado r = await client.EmitirAsync("0123456789001", comprobante, "FACTURA-2026-0001");
Console.WriteLine($"{r.Admission.Estado} {r.Admission.IdOperacion}");
```

```python-sdk
import json
import os
from ecuafact import EcuafactClient, EcuafactClientOptions, FacturaRequest

with open("comprobante.json", encoding="utf-8") as archivo:
    comprobante = FacturaRequest.model_validate(json.load(archivo))

with EcuafactClient(EcuafactClientOptions(
    base_address="https://api-sandbox.mynexusapi.com/",
    api_key=os.environ["ECUAFACT_API_KEY"],
)) as client:
    r = client.emitir_en("0123456789001", comprobante, "FACTURA-2026-0001")
    print(r.admission.estado, r.admission.cod_estado, r.admission.id_operacion)
```

```javascript-sdk
// Node.js 18 o superior. Guarda como emitir.mjs y ejecuta: node emitir.mjs
import { readFile } from "node:fs/promises";
import { EcuafactClient } from "@ecuafact/sdk";

const client = new EcuafactClient({
  baseAddress: "https://api-sandbox.mynexusapi.com/",
  apiKey: process.env.ECUAFACT_API_KEY
});
const comprobante = JSON.parse(await readFile("comprobante.json", "utf8"));

const r = await client.emitirFacturaEn("0123456789001", comprobante, "FACTURA-2026-0001");
console.log(r.admission.estado, r.admission.codEstado, r.admission.idOperacion);
```

```php-sdk
<?php
require __DIR__ . '/vendor/autoload.php';

use Ecuafact\Sdk\Contracts\FacturaRequest;
use Ecuafact\Sdk\EcuafactClient;
use Ecuafact\Sdk\EcuafactClientOptions;
use Ecuafact\Sdk\Support\Hydrator;

$client = new EcuafactClient(new EcuafactClientOptions(
    baseAddress: 'https://api-sandbox.mynexusapi.com/',
    apiKey: getenv('ECUAFACT_API_KEY'),
));
$comprobante = Hydrator::hydrate(FacturaRequest::class, json_decode(file_get_contents('comprobante.json')));

$r = $client->emitirEn('0123456789001', $comprobante, 'FACTURA-2026-0001');
echo $r->admission->estado . ' ' . $r->admission->codEstado . ' ' . $r->admission->idOperacion . PHP_EOL;
```

```java-sdk
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.EmisionResultado;
import com.ecuafact.sdk.contracts.FacturaRequest;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.nio.file.Files;
import java.nio.file.Path;

// Dentro de: public static void main(String[] args) throws Exception
EcuafactClient client = new EcuafactClient(
    EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY")));
FacturaRequest comprobante = new ObjectMapper()
    .readValue(Files.readString(Path.of("comprobante.json")), FacturaRequest.class);

EmisionResultado r = client.emitirEn("0123456789001", comprobante, "FACTURA-2026-0001");
System.out.println(r.admission().estado() + " " + r.admission().codEstado() + " " + r.admission().idOperacion());
```

`0123456789001` es la identificación de ejemplo de los
[datos de prueba](/v1/guias/datos-de-prueba). En tu código usa la que devuelve
tu [contexto](/v1/guias/consulta-contexto).

### Ejemplos completos

En [Ecuanexus/ecuafact-api-ejemplos](https://github.com/Ecuanexus/ecuafact-api-ejemplos)
encuentras ejemplos listos para ejecutar en los cinco lenguajes, cada uno en dos
variantes: con el SDK y con HTTP directo. Cada variante trae un script de
consola por tarea (contexto, validar, emitir, seguir, descargar el RIDE y el
XML, consultas al SRI, verificar la firma de un webhook
y manejo de errores) y una mini aplicación web que emite una factura de prueba
y recibe webhooks. Usan el ambiente de pruebas y toman tu contribuyente del
contexto, así que funcionan con tu sandbox sin editar nada.

## Información adicional

Puedes enviar en la cabecera `X-Additional-Info` un dato tuyo, como la versión
de tu ERP o la sucursal que emite, para que ubiquemos tus solicitudes cuando
nos pidas soporte. Configúrala en el cliente para que viaje en cada solicitud, o cámbiala
en una sola llamada con las opciones por llamada. Si una llamada no indica
valor, usa el del cliente, y si le pasas un valor vacío, esa llamada sale sin
la cabecera. La API la asocia a tu solicitud y no cambia la respuesta. Es la
única cabecera propia que admiten nuestros SDK. Las reglas del valor están en [Límites](/v1/guias/limites#cabeceras) y
el detalle de cada SDK en su guía: [.NET](/v1/guias/sdk-dotnet#informacion-adicional),
[Python](/v1/guias/sdk-python#informacion-adicional),
[Node.js](/v1/guias/sdk-node#informacion-adicional),
[PHP](/v1/guias/sdk-php#informacion-adicional) y
[Java](/v1/guias/sdk-java#informacion-adicional).

```csharp-sdk
using Ecuafact.Sdk;
using Ecuafact.Sdk.Contracts;

using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions
{
    BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"),
    ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!,
    AdditionalInfo = "erp=MiERP/4.2; sucursal=001"
});
Contexto contexto = await client.GetContextoAsync(opciones: new RequestOptions { AdditionalInfo = "erp=MiERP/4.2; lote=42" });
Console.WriteLine($"Contribuyentes: {contexto.Contribuyentes?.Count ?? 0}");
```

```python-sdk
import os
from ecuafact import EcuafactClient, EcuafactClientOptions, RequestOptions

with EcuafactClient(EcuafactClientOptions(
    base_address="https://api-sandbox.mynexusapi.com/",
    api_key=os.environ["ECUAFACT_API_KEY"],
    additional_info="erp=MiERP/4.2; sucursal=001",
)) as client:
    contexto = client.get_contexto(opciones=RequestOptions(additional_info="erp=MiERP/4.2; lote=42"))
    print(f"Contribuyentes: {len(contexto.contribuyentes or [])}")
```

```javascript-sdk
import { EcuafactClient } from "@ecuafact/sdk";

const client = new EcuafactClient({
  baseAddress: "https://api-sandbox.mynexusapi.com/",
  apiKey: process.env.ECUAFACT_API_KEY,
  additionalInfo: "erp=MiERP/4.2; sucursal=001"
});
const contexto = await client.getContexto({ additionalInfo: "erp=MiERP/4.2; lote=42" });
console.log(`Contribuyentes: ${contexto.contribuyentes.length}`);
```

```php-sdk
<?php
require __DIR__ . '/vendor/autoload.php';

use Ecuafact\Sdk\EcuafactClient;
use Ecuafact\Sdk\EcuafactClientOptions;
use Ecuafact\Sdk\RequestOptions;

$client = new EcuafactClient(new EcuafactClientOptions(
    baseAddress: 'https://api-sandbox.mynexusapi.com/',
    apiKey: getenv('ECUAFACT_API_KEY'),
    additionalInfo: 'erp=MiERP/4.2; sucursal=001',
));
$contexto = $client->getContexto(new RequestOptions(additionalInfo: 'erp=MiERP/4.2; lote=42'));
echo 'Contribuyentes: ' . count($contexto->contribuyentes ?? []) . PHP_EOL;
```

```java-sdk
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.RequestOptions;
import com.ecuafact.sdk.contracts.Contexto;

// Dentro de: public static void main(String[] args) throws Exception
EcuafactClient client = new EcuafactClient(
    EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY"))
        .additionalInfo("erp=MiERP/4.2; sucursal=001"));
Contexto contexto = client.getContexto(RequestOptions.create().additionalInfo("erp=MiERP/4.2; lote=42"));
System.out.println("Contribuyentes: " + contexto.contribuyentes().size());
```

Si el valor tiene tildes, `ñ`, saltos de línea, espacios al inicio o al final
o más de 256 caracteres, el SDK lanza `EcuafactConfigurationException` sin
llamar a la API.

## Cobertura

La tabla muestra qué operaciones cubre cada SDK. Python y PHP usan un tiempo
máximo en lugar de cancelación de llamadas. Los nombres exactos de cada método
están en la guía de tu lenguaje.

| Operación | Endpoint | .NET | Node.js | Python | Java | PHP |
|---|---|---|---|---|---|---|
| Contexto | `GET /v1/contexto` | Sí | Sí | Sí | Sí | Sí |
| Emitir | `POST /v1/contribuyentes/{identificacion}/{tipo}` (`{tipo}`: `facturas`, `liquidaciones-compra`, `notas-credito`, `notas-debito`, `guias-remision` o `retenciones`); la ruta sale de la clase del request (.NET, Python, Java, PHP) o del método por tipo (Node.js) | Sí | Sí | Sí | Sí | Sí |
| Seguimiento | `GET /v1/operaciones/{idOperacion}` | Sí | Sí | Sí | Sí | Sí |
| Listado de operaciones | `GET /v1/operaciones` | Sí | Sí | Sí | Sí | Sí |
| Descargar RIDE / XML | `GET .../comprobantes/{claveAcceso}/ride` y `/xml` | Sí | Sí | Sí | Sí | Sí |
| Cupo | `GET /v1/consumo` | Sí | Sí | Sí | Sí | Sí |
| Perfil del emisor (leer y actualizar) | `GET`/`PUT /v1/contribuyentes/{identificacion}/perfil` | Sí | Sí | Sí | Sí | Sí |
| Logo del perfil | `POST /v1/contribuyentes/{identificacion}/perfil/logo` | Sí | Sí | Sí | Sí | Sí |
| Consultas SRI (5 endpoints) | `GET /v1/consultas/...` | Sí | Sí | Sí | Sí | Sí |
| Verificar firma de webhook | - (local) | Sí | Sí | Sí | Sí | Sí |
| Evento de webhook tipado y varios secretos | - (local) | Sí | Sí | Sí | Sí | Sí |
| Verificar con `Ecuafact-Signature` o con Standard Webhooks | - (local) | Sí | Sí | Sí | Sí | Sí |
| Estado del servicio | `GET /estado` (sin API Key) | Sí | Sí | Sí | Sí | Sí |
| Comprobación de salud | `GET /salud` (sin API Key) | Sí | Sí | Sí | Sí | Sí |
| Catálogos del SRI | `GET /v1/catalogos` y `GET /v1/catalogos/{nombre}` | Sí | Sí | Sí | Sí | Sí |
| Esperar resultado | `GET /v1/operaciones/{idOperacion}` en bucle | Sí | Sí | Sí | Sí | Sí |
| Opciones por llamada (`RequestOptions`) | Todos los endpoints | Sí | Sí | Sí | Sí | Sí |
| Cancelar una llamada | Todos los endpoints | Sí (`CancellationToken`) | Sí (`signal`) | No (usa `timeout`) | Sí (`*Async` + `cancel`) | No (usa `timeout`) |
| Constructores opcionales de comprobantes (sin cálculo ni validación de negocio local) | - (local) | Sí | Sí | Sí | Sí | Sí |

Los SDK envían los comprobantes como JSON. Si quieres enviar el XML del SRI, usa HTTP directo, como se explica en [Emisión](/v1/guias/emision#cuerpo-json-o-xml).

Los cinco SDK incluyen métodos para listar operaciones; los nombres exactos están en la guía de tu lenguaje.
Para el estado del servicio y los catálogos, cada guía tiene una sección **Estado del servicio y catálogos**, por ejemplo la de
[SDK Node.js](/v1/guias/sdk-node#estado-del-servicio-y-catalogos). Las respuestas y sus campos son los de
[Estado del servicio](/v1/guias/estado-del-servicio) y [Catálogos](/v1/guias/catalogos#consultar-los-catalogos-por-api).

Los SDK verifican la firma de los webhooks que recibes. Los destinos de webhooks no se administran con los SDK: créalos y
gestiónalos desde el Portal del Cliente (**Integración > Eventos**), con el CLI (`ecuafact webhooks`), con el servidor MCP o con la
API REST, como se explica en [Administrar destinos por API](/v1/guias/webhooks#administrar-destinos-por-api).
Para listar operaciones también puedes usar el CLI (`ecuafact operaciones listar`) o HTTP directo, con las rutas y los ejemplos de
[Listado de operaciones](/v1/guias/consulta-operacion#listado-de-operaciones-por-contribuyente).

En .NET, igual que la API tiene un endpoint por tipo de documento, hay un request por tipo
(`FacturaRequest`, `LiquidacionCompraRequest`, `NotaCreditoRequest`, `NotaDebitoRequest`,
`GuiaRemisionRequest` y `RetencionRequest`), y `EmitirAsync` y `ValidarAsync` eligen la ruta
por el tipo del request que entregas. El cuerpo HTTP no lleva ningún campo de tipo; la validación
usa la misma ruta seguida de `/validar`. Los detalles están en [SDK .NET](/v1/guias/sdk-dotnet).

En PHP pasa igual: cada tipo tiene su clase (`FacturaRequest`, `LiquidacionCompraRequest`, `NotaCreditoRequest`,
`NotaDebitoRequest`, `GuiaRemisionRequest` y `RetencionRequest`, con su `Info*` y sus líneas), y `emitir`, `emitirEn`,
`validar` y `validarEn` eligen la ruta por la clase que entregas. El cuerpo no lleva ningún campo de tipo ni hay opción
de tipo en la llamada. Los detalles están en [SDK PHP](/v1/guias/sdk-php#tipo-de-comprobante-y-ruta).

En Node.js hay un método por tipo en lugar de una clase que decide la ruta: `emitirFactura`, `emitirLiquidacionCompra`,
`emitirNotaCredito`, `emitirNotaDebito`, `emitirGuiaRemision` y `emitirRetencion`, cada uno con su variante `...En`
(`emitirFacturaEn`) y su `validar<Tipo>` correspondiente; los tipos `FacturaRequest`, `LiquidacionCompraRequest` y los
demás describen el cuerpo. Los detalles están en [SDK Node.js](/v1/guias/sdk-node#tipo-de-comprobante-y-ruta).

En Python y Java también hay una clase por tipo (`FacturaRequest`, `LiquidacionCompraRequest`, `NotaCreditoRequest`,
`NotaDebitoRequest`, `GuiaRemisionRequest` y `RetencionRequest`), y `emitir`, `emitir_en` / `emitirEn`, `validar` y
`validar_en` / `validarEn` eligen la ruta por la clase que entregas; el cuerpo tampoco lleva campo de tipo. Los detalles
están en [SDK Python](/v1/guias/sdk-python#tipo-de-comprobante) y
[SDK Java](/v1/guias/sdk-java#ruta-de-emision-por-tipo-de-comprobante).

## Nombres equivalentes

Entre los cinco SDK cambian la convención de nombres y la unidad de tiempo que
usa cada lenguaje. Usa esta tabla para
pasar un ejemplo de un lenguaje a otro.

| Concepto | .NET | Java | Node.js | Python | PHP |
|---|---|---|---|---|---|
| Esperar resultado | `EsperarResultadoAsync(id, intervalo?, maximo?)` (`TimeSpan`) | `esperarResultado(id, intervalo, maximo)` (`Duration`) | `esperarResultado(id, { intervaloMs, maximoMs, signal })` | `esperar_resultado(id, intervalo=5.0, maximo=120.0)` (segundos) | `esperarResultado($id, $intervalo = 5.0, $maximo = 120.0)` (segundos) |
| Comprobar salud (`GET /salud`) | `SaludAsync()` | `obtenerSalud()` | `getSalud()` | `get_salud()` | `obtenerSalud()` |
| Estado del servicio (`GET /estado`) | `ObtenerEstadoServicioAsync()` | `obtenerEstadoServicio()` | `getEstadoServicio()` | `get_estado_servicio()` | `obtenerEstadoServicio()` |
| Índice de catálogos | `ListarCatalogosAsync()` | `listarCatalogos()` | `listarCatalogos()` | `listar_catalogos()` | `listarCatalogos()` |
| Catálogo por clave | `ObtenerCatalogoAsync(nombre)` | `obtenerCatalogo(nombre)` | `getCatalogo(nombre)` | `get_catalogo(nombre)` | `obtenerCatalogo($nombre)` |
| Subir logo | `ActualizarLogoAsync(...)` | `actualizarLogo(...)` | `actualizarLogo(...)` | `actualizar_logo(...)` | `actualizarLogo(...)` |
| Evento de webhook | `WebhookEvent.Construir(secretos, cabecera, cuerpo)` | `WebhookEvent.construir(secretos, cabecera, cuerpo)` | `construirEvento(secretos, cabecera, cuerpo)` | `construir_evento(secretos, cabecera, cuerpo)` | `WebhookEvent::construir($secretos, $cabecera, $cuerpo)` |
| Tipo del evento | `evento.Tipo` | `evento.eventType()` | `evento.eventType` | `evento.event_type` | `$evento->eventType` |
| Estado final / autorizado | `operacion.EsFinal` / `EsAutorizado` | `operacion.esFinal()` / `esAutorizado()` | `esFinal(operacion)` / `esAutorizado(operacion)` | `operacion.es_final` / `es_autorizado` | `$operacion->esFinal()` / `esAutorizado()` |
| Estado tipado | `operacion.EstadoOperacion` | `estadoOperacion()` | `estadoOperacion(op)` | `estado_operacion` | `estadoOperacion()` |
| Código del resultado | `operacion.CodEstado` | `operacion.codEstado()` | `operacion.codEstado` | `operacion.cod_estado` | `$operacion->codEstado` |
| Código de una excepción | `error.CodEstado` | `error.codEstado()` | `error.codEstado` | `error.cod_estado` | `$error->codEstado` |
| Constantes del catálogo | `CodEstado.ComprobanteInvalido` | `CodEstado.COMPROBANTE_INVALIDO` | `CodEstado.ComprobanteInvalido` | `CodEstado.COMPROBANTE_INVALIDO` | `CodEstado::COMPROBANTE_INVALIDO` |
| No reintentar el 429 con el `codEstado` 5005 (`limite_solicitudes`), que se reintenta por defecto | `RetryRateLimited = false` | `retryRateLimited(false)` | `retryRateLimited: false` | `retry_rate_limited=False` | `retryRateLimited: false` |
| Códigos reintentables | `RetryableStatusCodes` | `retryableStatusCodes(...)` | `retryableStatusCodes` | `retry_status_codes` | `retryableStatusCodes` |
| Espera base | `RetryBaseDelay` | `retryBaseDelay(...)` | `retryBaseDelayMs` | `retry_base_delay_ms` | `retryBaseDelaySeconds` |
| Backoff | `RetryBackoff.Linear` / `Exponential` | `RetryBackoff.LINEAR` / `EXPONENTIAL` | `"linear"` / `"exponential"` | `RetryBackoff.LINEAR` / `EXPONENTIAL` | `RetryBackoff::Linear` / `Exponential` |
| Variación aleatoria | `RetryJitter` | `retryJitter(...)` | `retryJitterMs` | `retry_jitter_ms` | `retryJitterSeconds` |
| Tiempo por intento (30 s por defecto) | `Timeout` | `timeout(Duration)` | `timeoutMs` | `timeout` (segundos) | `timeout` (segundos) |
| Tope de tiempo total | `TotalTimeout` | `totalTimeout(...)` | `totalTimeoutMs` | `total_timeout` | `totalTimeoutSeconds` |
| Información adicional (`X-Additional-Info`) | `AdditionalInfo` | `additionalInfo(String)` | `additionalInfo` | `additional_info` | `additionalInfo` |
| Conexión (proxy, TLS) | `Handler` | `httpClient`, `proxy`, `sslContext`, `connectTimeout` | `dispatcher` | `http_client`, `proxy`, `verify`, `connect_timeout` | `proxy`, `caInfo`, `connectTimeout`, `transport` |
| Espera sugerida en el error | `RetryAfter` (`TimeSpan?`) | `retryAfter()` (`Duration`) | `retryAfterMs` | `retry_after` (`timedelta`) | `retryAfter` (segundos) |
| Reintentable | `EsReintentable` | `esReintentable()` | `esReintentable` | `es_reintentable` | `esReintentable` |
| Cupo agotado | `EcuafactQuotaException` | `EcuafactQuotaException` | `EcuafactQuotaException` | `EcuafactQuotaException` | `EcuafactQuotaException` |
| Opciones por llamada | `RequestOptions` (último parámetro `opciones`) | `RequestOptions.create()` (sobrecarga con `RequestOptions` al final) | objeto `RequestOptions` (último parámetro) | `opciones=RequestOptions(...)` | `?RequestOptions $opciones` (último argumento) |
| Tiempo por intento en una llamada | `Timeout` (`TimeSpan`) | `timeout(Duration)` | `timeoutMs` | `timeout` (segundos) | `timeout` (segundos) |
| Tope total de una llamada | `TotalTimeout` (`TimeSpan`) | `totalTimeout(Duration)` | `totalTimeoutMs` | `total_timeout` (segundos) | `totalTimeout` (segundos) |
| Correlación propia | `CorrelationId` | `correlationId(...)` | `correlationId` | `correlation_id` | `correlationId` |
| Sin reintentos en una llamada | `Reintentos = false` | `reintentos(false)` | `reintentos: false` | `reintentos=False` | `reintentos: false` |
| Información adicional en una llamada | `AdditionalInfo` | `additionalInfo(String)` | `additionalInfo` | `additional_info` | `additionalInfo` |
| Cancelar una llamada | `CancellationToken` | variante `*Async` y `cancel(true)` | `signal` (`AbortSignal`) | No hay: usa `timeout` y `total_timeout` | No hay: usa `timeout` y `totalTimeout` |
| Constructor de comprobantes | `ComprobanteBuilder.Factura(ruc, estab, ptoEmi)` | `ComprobanteBuilder.factura(ruc, estab, ptoEmi)` | `ComprobanteBuilder.factura(ruc, estab, ptoEmi)` | `ComprobanteBuilder.factura(ruc, estab, pto_emi)` | `ComprobanteBuilder::factura($ruc, $estab, $ptoEmi)` |
| Tarifa de una línea | `new Impuesto { Codigo = "2", CodigoPorcentaje = "4", Tarifa = 15m }` | `Tarifa.of("4", new BigDecimal("15"))` | `{ codigoPorcentaje: "4", tarifa: 15 }` | `Tarifa("4", 15)` o `("4", 15)` | `Tarifa::iva('4', 15)` |

## Siguientes pasos

- [SDK .NET](/v1/guias/sdk-dotnet), [Node.js](/v1/guias/sdk-node), [Python](/v1/guias/sdk-python), [Java](/v1/guias/sdk-java) o [PHP](/v1/guias/sdk-php): instala el de tu lenguaje y ejecuta su quickstart, que va de la API Key al RIDE.
- [Primeros pasos](/v1/guias/primeros-pasos): sigue el mismo flujo por HTTP directo, sin SDK.
- [Webhooks](/v1/guias/webhooks): recibe el resultado del SRI y verifica su firma con el SDK.

