# El contrato OpenAPI

> La especificación OpenAPI 3.0 de la API de Simplo — descárgala, impórtala en Postman o genera un cliente C#, Java o TypeScript desde el contrato.

La API REST de Simplo se describe con un contrato **OpenAPI 3.0** — el mismo
que alimenta la [referencia por endpoint](/api/) de este sitio. Es el
artefacto canónico de integración: si tu stack es .NET, Java, SAP, NetSuite o
cualquier otro, no necesitas un SDK nuestro — necesitas el contrato.

**Descarga:** [`https://docs.simplo.cl/openapi.yaml`](/openapi.yaml)

```bash
curl -O https://docs.simplo.cl/openapi.yaml
```

> **Beta privada:**
> El contrato describe la superficie completa de la API, pero la emisión de DTE
> con API key está en **beta privada**: hoy las API keys operan en modo lectura
> y el acceso de escritura se habilita cuenta por cuenta. Pide acceso en
> [hola@simplo.cl](mailto:hola@simplo.cl).

## Qué garantiza el contrato

- **Versionado con la API.** El contrato lleva la versión de la API
  (`info.version`) y evoluciona junto al servicio.
- **Cambios aditivos dentro de `/v1`.** Dentro de `/api/v1` los cambios son
  aditivos: campos y endpoints nuevos pueden aparecer, pero los existentes no
  cambian de forma incompatible. Escribe tu deserialización tolerante a campos
  desconocidos.
- **Errores uniformes.** Todos los errores usan el sobre `ErrorResponse`
  (`code` máquina-legible + `message`) — ver [Errores](/referencia/errores/).

## Genera un cliente desde el contrato

### C# / .NET — openapi-generator

```bash
# requiere Java; también disponible vía Docker o npm (@openapitools/openapi-generator-cli)
openapi-generator-cli generate \
  -i https://docs.simplo.cl/openapi.yaml \
  -g csharp \
  --library httpclient \
  -o ./simplo-client-csharp \
  --additional-properties=packageName=Simplo.Api,targetFramework=net8.0
```

### C# / .NET — NSwag

```bash
dotnet tool install -g NSwag.ConsoleCore
nswag openapi2csclient \
  /input:https://docs.simplo.cl/openapi.yaml \
  /classname:SimploClient \
  /namespace:Simplo.Api \
  /output:SimploClient.cs
```

### Java — openapi-generator

```bash
openapi-generator-cli generate \
  -i https://docs.simplo.cl/openapi.yaml \
  -g java \
  --library native \
  -o ./simplo-client-java \
  --additional-properties=groupId=cl.simplo,artifactId=simplo-api-client
```

`--library native` usa `java.net.http.HttpClient` (Java 11+), sin
dependencias pesadas; `okhttp-gson` y `resttemplate` también funcionan.

### Postman / Insomnia / Bruno

Importa la URL directamente: **Import → Link →**
`https://docs.simplo.cl/openapi.yaml`. Obtienes las colecciones con los 27
endpoints, ejemplos de request/response y los esquemas de autenticación
(`X-Api-Key` y Bearer) listos para configurar.

### TypeScript

Para TypeScript ya existe un cliente oficial generado y mantenido desde este
mismo contrato: [`@simplohq/sdk`](/agentes/sdk/). Si prefieres generar el
tuyo:

```bash
npx openapi-typescript https://docs.simplo.cl/openapi.yaml -o simplo-api.d.ts
```

## Validación

El contrato se valida con [Redocly CLI](https://redocly.com/docs/cli/) antes
de cada publicación:

```bash
npx @redocly/cli lint https://docs.simplo.cl/openapi.yaml
```

## Relacionado

- [Referencia por endpoint](/api/) — los 27 endpoints navegables, con
  ejemplos en curl, C#, Java y JavaScript
- [Autenticación](/comienza/autenticacion/) — API keys y su ciclo de vida
- [Errores](/referencia/errores/) — el sobre `ErrorResponse` y códigos
- [Quickstart](/comienza/quickstart/) — tu primera emisión, REST primero

---

Versión HTML: https://docs.simplo.cl/referencia/contrato-openapi/ · Índice para agentes: https://docs.simplo.cl/llms.txt