The OpenAPI contract

Simplo’s REST API is described by an OpenAPI 3.0 contract — the same one that powers this site’s endpoint reference. It’s the canonical integration artifact: whether your stack is .NET, Java, SAP, NetSuite or anything else, you don’t need one of our SDKs — you need the contract.

Download: https://docs.simplo.cl/openapi.yaml

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

Not all of the contract is reachable by API key

The contract describes the full invoicing API surface, but a billing:dte API key can only call the five DTE routes (emit, list, detail, PDF, XML) — the rest (CAF, company, certificate, webhooks, customers, products) is session-only and responds 403 BILLING_API_KEY_ROUTE_NOT_ALLOWED to a key. See the quickstart’s table.

What the contract guarantees

• Versioned with the API. The contract carries the API version (info.version) and evolves alongside the service.
• Additive changes within /v1. Within /api/v1, changes are additive: new fields and endpoints may appear, but existing ones don’t change in incompatible ways. Write your deserialization tolerant of unknown fields.
• Uniform errors. Every error uses the ErrorResponse envelope (machine-readable code + message) — see Errors.
• Emission as a discriminated union. The POST /billing/dte body is the EmitirDTERequestPorTipo schema: a oneOf of 12 variants discriminated on tipo_dte, each declaring its type’s conditionally-required fields and its measured extensions (x-simplo-price-semantics, x-simplo-sandbox-leniency). A client generator or schema validator enforces the per-type rules without you coding them — see Payloads by type.

Generate a client from the contract

C# / .NET — openapi-generator

# requires Java; also available via Docker or 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

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

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 uses java.net.http.HttpClient (Java 11+), with no heavy dependencies; okhttp-gson and resttemplate also work.

Postman / Insomnia / Bruno

Import the URL directly: Import → Link → https://docs.simplo.cl/openapi.yaml. You get collections with all 27 endpoints, request/response examples and the authentication schemes (X-Api-Key and Bearer) ready to configure.

TypeScript

For TypeScript there will be an official client maintained on top of this same contract: @simplohq/sdk (not yet published on npm). In the meantime, generate your own:

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

Validation

The contract is validated with Redocly CLI before every publish:

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

Related

• Endpoint reference — the 27 browsable endpoints, with examples in curl, C#, Java and JavaScript
• Authentication — API keys and their lifecycle
• Errors — the ErrorResponse envelope and codes
• Quickstart — your first emission, REST-first