Descripción general

Simplo API 0.4.0

API REST de facturación electrónica chilena (DTE) de Simplo.

Permite emitir y consultar Documentos Tributarios Electrónicos (DTE), administrar CAFs (folios autorizados por el SII), datos de la empresa emisora, certificado digital, webhooks de eventos, y catálogos de clientes y productos.

Autenticación

Dos mecanismos:

• API Key (X-Api-Key): integraciones servidor a servidor, scope billing:dte. La key fija la empresa y el ambiente: sk_simplo_sandbox_... emite en el sandbox (self-serve, se crea en app.simplo.cl → Desarrolladores); sk_simplo_... emite en producción (se habilita por empresa — [email protected]).
• Bearer JWT (Authorization: Bearer ...): token de sesión de la plataforma Simplo, usado por las aplicaciones oficiales.

Superficie por API key: una key billing:dte solo puede llamar POST /billing/dte, GET /billing/dte, GET /billing/dte/{id} y sus descargas /pdf y /xml. Toda otra operación de este contrato es solo sesión (JWT) y responde 403 BILLING_API_KEY_ROUTE_NOT_ALLOWED ante una API key; cada operación lo indica en su descripción y en su campo security.

Toda petición opera en el contexto de la empresa (tenant) asociada a la credencial. No es necesario enviar el RUT de la empresa emisora en cada llamada.

Emisión de DTE (flujo asíncrono)

POST /api/v1/billing/dte valida el documento, asigna folio desde el CAF activo, genera el XML, lo timbra (TED) y lo firma digitalmente. La respuesta 201 retorna de inmediato con estado firmado. El envío al SII ocurre de forma asíncrona: siga el estado con GET /api/v1/billing/dte/{id} (polling). (La entrega de webhooks aún no está activa.)

Idempotencia

POST /api/v1/billing/dte exige el header Idempotency-Key (UUID). Reintentar con la misma key retorna la respuesta original con el header X-Idempotency-Replay: true. Reutilizar una key con un body distinto retorna 422 (IDEMPOTENCY_BODY_MISMATCH); una key aún en proceso retorna 409 (IDEMPOTENCY_IN_PROGRESS).

Paginación

Los listados paginados usan cursor: parámetros cursor y limit; la respuesta incluye items (o data en clientes/productos), next_cursor (null cuando no hay más páginas) y, donde aplica, total_count.

Errores

Todos los errores usan un sobre común (ErrorResponse) con code máquina-legible y message descriptivo; los errores de validación agregan details por campo.

Simplo

• https://simplo.cl
• [email protected]

Information

• OpenAPI version: 3.0.3

Operaciones

GET

/api/v1/billing/dte

POST

/api/v1/billing/dte

GET

/api/v1/billing/dte/{id}

GET

/api/v1/billing/dte/{id}/pdf

GET

/api/v1/billing/dte/{id}/xml

GET

/api/v1/billing/caf

POST

/api/v1/billing/caf

GET

/api/v1/billing/caf/{id}

GET

/api/v1/billing/empresa

PUT

/api/v1/billing/empresa

GET

/api/v1/billing/empresa/certificado

POST

/api/v1/billing/empresa/certificado/pfx

GET

/api/v1/billing/webhooks

POST

/api/v1/billing/webhooks

DELETE

/api/v1/billing/webhooks/{id}

GET

/api/v1/billing/clientes

POST

/api/v1/billing/clientes

GET

/api/v1/billing/clientes/search

GET

/api/v1/billing/clientes/{id}

PUT

/api/v1/billing/clientes/{id}

DELETE

/api/v1/billing/clientes/{id}

GET

/api/v1/billing/productos

POST

/api/v1/billing/productos

GET

/api/v1/billing/productos/search

GET

/api/v1/billing/productos/{id}

PUT

/api/v1/billing/productos/{id}

DELETE

/api/v1/billing/productos/{id}

Autenticación

ApiKeyAuth

API key de integración servidor a servidor (scope billing:dte). sk_simplo_sandbox_... opera el sandbox de la empresa; sk_simplo_... opera producción. Solo alcanza las cinco operaciones DTE (emitir, listar, detalle, PDF, XML); el resto del contrato es solo sesión (JWT) y responde 403 BILLING_API_KEY_ROUTE_NOT_ALLOWED.

Security scheme type: apiKey

Header parameter name: X-Api-Key

BearerAuth

JWT de sesión de la plataforma Simplo (RS256). Contiene el contexto de la empresa (tenant) para multi-tenancy.

Security scheme type: http

Bearer format: JWT