Retenciones

POST /api/v1/withholdings/issue · scope documents:write

Un comprobante de retención declara lo que tu negocio retiene al pagar a un proveedor: un porcentaje de renta sobre la base, un porcentaje del IVA de la compra, o ISD. Va siempre atado al comprobante de compra que la sustenta, normalmente la factura del proveedor.

{
  "sujeto_retenido": { "identificacion": "1791234567001", "razon_social": "SUMINISTROS DEL PACÍFICO S.A." },
  "documento_sustento": { "tipo": "01", "numero": "002-001-000004521", "fecha_emision": "2026-09-20" },
  "retenciones": [
    { "impuesto": "renta", "codigo": "312", "base_imponible": 1000.00, "porcentaje": 1.75 },
    { "impuesto": "iva", "codigo": "1", "base_imponible": 150.00, "porcentaje": 30 }
  ]
}

Campos de primer nivel

Campo	Obligatorio	Por defecto	Notas
sujeto_retenido	✅	—	El proveedor. Identificado: no admite consumidor final
retenciones	✅	—	Una línea por impuesto retenido
documento_sustento	✅*	—	El comprobante de compra. *Cada línea puede indicar el suyo
periodo_fiscal	—	El mes de fecha_emision	MM/YYYY
referencia_externa	—	—	Envíala siempre. Única por negocio entre retenciones
fecha_emision	—	Hoy en Ecuador	No puede ser futura
establecimiento	—	El de la clave o el del negocio	{ "codigo", "punto_emision" }
secuencial	—	El siguiente de la serie de retenciones	Solo si controlas la numeración
enviar_email	—	true	Enviar el RIDE al correo del sujeto retenido al autorizarse

sujeto_retenido

{
  "tipo_identificacion": "04",
  "identificacion": "1791234567001",
  "razon_social": "SUMINISTROS DEL PACÍFICO S.A.",
  "email": "cobros@pacifico.ec",
  "direccion": "Av. Juan Tanca Marengo, Guayaquil"
}

tipo_identificacion se deduce de la identificación si falta. Si la clave tiene «crear contactos» activado, el proveedor se da de alta en Olympus la primera vez.

documento_sustento

{ "tipo": "01", "numero": "002-001-000004521", "fecha_emision": "2026-09-20", "codigo_sustento": "01" }

Campo	Obligatorio	Por defecto	Notas
tipo	—	01	Tipo del comprobante sustento; ver GET /catalogs/document-types
numero	✅	—	Número completo, 001-001-000000123
fecha_emision	✅	—	Fecha del comprobante sustento
codigo_sustento	—	02	Sustento tributario (codSustento); ver GET /catalogs/support-types

Puedes ponerlo una vez, a nivel de la retención, y vale para todas las líneas; o ponerlo dentro de una línea concreta cuando esa línea sustenta otro comprobante. Si falta en los dos sitios, la petición no pasa la validación.

codigo_sustento

Dice para qué usa tu negocio esa compra: 01 crédito tributario de IVA (lo habitual si estás obligado a llevar contabilidad), 02 costo o gasto para renta, 06/07 inventario… No afecta a la autorización del SRI, pero sí a tus anexos. Si no lo envías, Olympus usa 02.

retenciones

{ "impuesto": "renta", "codigo": "312", "base_imponible": 1000.00, "porcentaje": 1.75 }

Campo	Obligatorio	Notas
impuesto	✅	renta, iva o isd
codigo	✅	Código de retención del SRI para ese impuesto
base_imponible	✅	Sobre qué se retiene: el subtotal de la compra en renta, su IVA en la retención de IVA
porcentaje	✅	Lo que se retiene, en porcentaje (1.75, 30, 100)
valor	—	Si lo envías se comprueba contra base × porcentaje
documento_sustento	—	Solo si esta línea sustenta otro comprobante

Los códigos y sus porcentajes están en GET /catalogs/retention-codes, con impuesto ya resuelto:

{ "impuesto": "renta", "codigo": "312", "nombre": "Transferencia de bienes muebles de naturaleza corporal", "porcentaje": 1.75, "porcentaje_variable": false }
{ "impuesto": "iva", "codigo": "1", "nombre": "Retención IVA 30%", "porcentaje": 30.0, "porcentaje_variable": false }

Olympus no valida la combinación código–porcentaje: la valida el SRI al autorizar. Si te equivocas, la retención vuelve no_autorizado con el mensaje del SRI en mensajes, y puedes corregirla desde Olympus y reintentar.

Respuesta

202 Accepted:

{
  "id": "c3d8f0a2-6b1e-4c7a-8d92-5e4f3a2b1c09",
  "tipo": "retencion",
  "estado": "pendiente",
  "secuencial": "001-001-000000210",
  "clave_acceso": "2509202607099999999900110010010000002101234567812",
  "sujeto_retenido": { "tipo_identificacion": "04", "identificacion": "1791234567001", "razon_social": "SUMINISTROS DEL PACÍFICO S.A.", "email": "cobros@pacifico.ec", "telefono": null, "direccion": null },
  "periodo_fiscal": "09/2026",
  "total_retenido": 62.5,
  "retenciones": [
    { "impuesto": "renta", "codigo": "312", "base_imponible": 1000.0, "porcentaje": 1.75, "valor": 17.5, "documento_sustento": { "tipo": "01", "numero": "002-001-000004521", "fecha_emision": "2026-09-20", "codigo_sustento": "01" } },
    { "impuesto": "iva", "codigo": "1", "base_imponible": 150.0, "porcentaje": 30.0, "valor": 45.0, "documento_sustento": { "tipo": "01", "numero": "002-001-000004521", "fecha_emision": "2026-09-20", "codigo_sustento": "01" } }
  ],
  "urls": { "detalle": "https://olympus.atharix.com/api/v1/withholdings/c3d8f0a2-…", "pdf": null, "xml": null, "publica": null }
}

Ejemplo completo

curl

curl -X POST https://olympus.atharix.com/api/v1/withholdings/issue \
  -H "X-API-Key: $OLYMPUS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: RET-2026-0210" \
  -d '{
    "referencia_externa": "RET-2026-0210",
    "sujeto_retenido": {
      "identificacion": "1791234567001",
      "razon_social": "SUMINISTROS DEL PACÍFICO S.A.",
      "email": "cobros@pacifico.ec"
    },
    "periodo_fiscal": "09/2026",
    "documento_sustento": { "tipo": "01", "numero": "002-001-000004521", "fecha_emision": "2026-09-20", "codigo_sustento": "01" },
    "retenciones": [
      { "impuesto": "renta", "codigo": "312", "base_imponible": 1000.00, "porcentaje": 1.75 },
      { "impuesto": "iva", "codigo": "1", "base_imponible": 150.00, "porcentaje": 30 }
    ]
  }'

Python

import os, requests

retencion = requests.post(
    "https://olympus.atharix.com/api/v1/withholdings/issue",
    headers={"X-API-Key": os.environ["OLYMPUS_API_KEY"], "Idempotency-Key": "RET-2026-0210"},
    json={
        "referencia_externa": "RET-2026-0210",
        "sujeto_retenido": {
            "identificacion": "1791234567001",
            "razon_social": "SUMINISTROS DEL PACÍFICO S.A.",
            "email": "cobros@pacifico.ec",
        },
        "periodo_fiscal": "09/2026",
        "documento_sustento": {"tipo": "01", "numero": "002-001-000004521", "fecha_emision": "2026-09-20", "codigo_sustento": "01"},
        "retenciones": [
            {"impuesto": "renta", "codigo": "312", "base_imponible": 1000.00, "porcentaje": 1.75},
            {"impuesto": "iva", "codigo": "1", "base_imponible": 150.00, "porcentaje": 30},
        ],
    },
    timeout=30,
)
retencion.raise_for_status()
print(retencion.json()["total_retenido"])

Node

const response = await fetch("https://olympus.atharix.com/api/v1/withholdings/issue", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.OLYMPUS_API_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": "RET-2026-0210",
  },
  body: JSON.stringify({
    referencia_externa: "RET-2026-0210",
    sujeto_retenido: {
      identificacion: "1791234567001",
      razon_social: "SUMINISTROS DEL PACÍFICO S.A.",
      email: "cobros@pacifico.ec",
    },
    periodo_fiscal: "09/2026",
    documento_sustento: { tipo: "01", numero: "002-001-000004521", fecha_emision: "2026-09-20", codigo_sustento: "01" },
    retenciones: [
      { impuesto: "renta", codigo: "312", base_imponible: 1000.0, porcentaje: 1.75 },
      { impuesto: "iva", codigo: "1", base_imponible: 150.0, porcentaje: 30 },
    ],
  }),
});
const retencion = await response.json();
console.log(retencion.total_retenido);

PHP

$client = new \GuzzleHttp\Client(['base_uri' => 'https://olympus.atharix.com/api/v1/']);
$response = $client->post('withholdings/issue', [
    'headers' => ['X-API-Key' => getenv('OLYMPUS_API_KEY'), 'Idempotency-Key' => 'RET-2026-0210'],
    'json' => [
        'referencia_externa' => 'RET-2026-0210',
        'sujeto_retenido' => [
            'identificacion' => '1791234567001',
            'razon_social' => 'SUMINISTROS DEL PACÍFICO S.A.',
            'email' => 'cobros@pacifico.ec',
        ],
        'periodo_fiscal' => '09/2026',
        'documento_sustento' => ['tipo' => '01', 'numero' => '002-001-000004521', 'fecha_emision' => '2026-09-20', 'codigo_sustento' => '01'],
        'retenciones' => [
            ['impuesto' => 'renta', 'codigo' => '312', 'base_imponible' => 1000.00, 'porcentaje' => 1.75],
            ['impuesto' => 'iva', 'codigo' => '1', 'base_imponible' => 150.00, 'porcentaje' => 30],
        ],
    ],
]);
$retencion = json_decode((string) $response->getBody(), true);
echo $retencion['total_retenido'];