Otros comprobantes · Ecuador

Otros comprobantes electrónicos

Además de la factura, la API emite los otros cinco comprobantes electrónicos del SRI. Cada uno es un recurso con las mismas siete operaciones que /invoices, así que si ya integraste la factura, el resto te va a resultar familiar.

Comprobante	Recurso	Para qué
Nota de crédito	`/credit-notes`	Devolver o descontar sobre una factura ya autorizada
Nota de débito	`/debit-notes`	Cobrar de más sobre una factura: intereses, gastos
Comprobante de retención	`/withholdings`	Retener renta, IVA o ISD a un proveedor
Guía de remisión	`/waybills`	Respaldar el traslado de mercancía
Liquidación de compra	`/purchase-settlements`	Comprar a quien no puede emitir comprobantes

Los permisos

Hacen falta dos scopes nuevos en la clave: documents:write para emitir, reintentar y reenviar por correo, y documents:read para consultar, listar y descargar. Una clave con solo invoices:* recibe 403 insufficient_scope.

Se marcan al crear la clave en Olympus, en Configuración → Integraciones → Nueva clave: «Emitir otros comprobantes» y «Consultar comprobantes». Si ya tienes una clave y quieres ampliarla, rótala con los permisos nuevos; ver Crear tu API key.

Las siete operaciones

Cambia {recurso} por el de la tabla de arriba:

Operación	Ruta	Scope
Emitir	`POST /{recurso}/issue`	`documents:write`
Listar	`GET /{recurso}`	`documents:read`
Consultar	`GET /{recurso}/{id}`	`documents:read`
Descargar el RIDE	`GET /{recurso}/{id}/pdf`	`documents:read`
Descargar el XML autorizado	`GET /{recurso}/{id}/xml`	`documents:read`
Reintentar el envío al SRI	`POST /{recurso}/{id}/retry`	`documents:write`
Reenviar por correo	`POST /{recurso}/{id}/send-email`	`documents:write`

Y, como con cualquier comprobante de Ecuador, GET /documents/{clave_acceso} lo devuelve por su clave de acceso, con la forma de su recurso.

Lo que comparten con la factura

Responden 202. El comprobante se firma y se envía al SRI en segundo plano; la respuesta trae la clave_acceso y el estado pendiente. Consulta el detalle o espera el correo. Los estados son los mismos que los de la factura.
referencia_externa es tu identificador y es única por negocio y tipo de comprobante: repetirla responde 409 external_id_conflict con el que ya existe. Envíala siempre.
Idempotency-Key funciona igual: mismo cuerpo, misma respuesta; ver Idempotencia.
establecimiento y secuencial se comportan como en la factura: cada tipo de comprobante tiene su propia serie por punto de emisión, y Olympus asigna el siguiente número salvo que lo impongas.
enviar_email (donde hay una contraparte con correo) manda el RIDE y el XML al autorizarse. Con false, Olympus no escribe a nadie.
Los impuestos de las líneas se declaran igual que en la factura, con codigo 2 y el codigo_porcentaje del SRI; ver IVA y códigos del SRI.
La respuesta tiene la misma cabecera común (id, tipo, estado, clave_acceso, numero_autorizacion, secuencial, ambiente, mensajes, urls…) y, después, los campos propios de cada comprobante.

Errores propios de esta sección

`code`	HTTP	Cuándo
`invoice_not_found`	422	La factura de `factura_modificada` o de `destinatarios[].factura` no existe en el negocio
`invoice_not_authorized`	409	Esa factura está anulada o el SRI todavía no la autorizó
`document_type_not_supported`	422	El negocio es español

El resto de errores son los de siempre; ver la tabla de errores.

Catálogos que te harán falta

Catálogo	Para
`GET /catalogs/retention-codes`	Códigos y porcentajes de retención de renta, IVA e ISD
`GET /catalogs/support-types`	Sustentos tributarios de una retención (`codigo_sustento`)
`GET /catalogs/document-types`	Tipos de comprobante sustento o relacionado (`tipo`)
`GET /catalogs/tax-rates`	Códigos de IVA de las líneas