Retenciones

Cuando eres agente de retención y le pagas a un proveedor, le emites un comprobante de retención (07). En Chaski tu emisor es el agente de retención y subject es el proveedor. El ciclo es el mismo de las facturas (pending → authorized/rejected).

curl https://api.chaski.ec/v1/withholdings \
  -H "Authorization: Bearer $CHASKI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: retencion-fact-123" \
  -d '{
    "issuer": "iss_01jbx3k9q2f8m4tn6vwz0yh5ce",
    "emission_point": "001-003",
    "subject": {
      "id_type": "ruc", "id": "1790012345001",
      "name": "Proveedor S.A.", "email": "[email protected]"
    },
    "documents": [{
      "support_code": "01",
      "type": "01",
      "number": "001-001-000000123",
      "issue_date": "2026-11-01",
      "subtotal": "100.00",
      "total": "115.00",
      "taxes": [{ "type": "iva", "rate": "15", "base": "100.00", "amount": "15.00" }],
      "withholdings": [
        { "tax": "income", "code": "312", "base": "100.00", "rate": "1.75" },
        { "tax": "iva", "code": "1", "base": "15.00" }
      ],
      "payments": [{ "method": "other_financial_system" }]
    }]
  }'

La respuesta trae cada retención con su valor (amount) y el total retenido (total_withheld, en este ejemplo 6.25).

Documentos de sustento

Cada elemento de documents es el comprobante del proveedor sobre el que retienes, normalmente su factura. Se copian sus datos tal como están en ese documento:

• support_code: código de sustento del ATS (tabla 5), por ejemplo 01, crédito tributario para declaración de IVA.
• type: tipo de documento del ATS (tabla 4): 01 factura, 03 liquidación de compra…
• number, issue_date y, si quieres, authorization_number (la clave de acceso de 49 dígitos).
• subtotal, total y taxes: los impuestos del documento (iva con su tarifa, o ice/irbpnr con rate_code y rate).
• payments: cómo se pagó. Deben sumar total; con una sola forma de pago se puede omitir el monto.
• foreign_payment: solo si el pago fue al exterior (régimen, código de país del ATS, convenio de doble tributación).

Una retención puede tener hasta 50 documentos de sustento del mismo proveedor.

Cómo se calcula lo retenido

amount = base × rate / 100, redondeado a 2 decimales.

tax	Base	Porcentaje
income (renta)	Hasta el subtotal del documento	Obligatorio. Lo indicas tú según el código del ATS (303, 312, 343…), porque cambia por resolución.
iva	Hasta el IVA del documento	Sale del código: 9 10 %, 10 20 %, 1 30 %, 11 50 %, 2 70 %, 3 100 %, 7 y 8 0 %. Si lo mandas y no coincide: 400 withholding_rate_mismatch.
isd	La que corresponda	Obligatorio.

El porcentaje admite hasta 3 cifras, con hasta 2 decimales: 1.75, 30 y 100 sí; 12.75 no.

Otros datos

• fiscal_period (AAAA-MM): por defecto, el mes de emisión. No puede ser posterior.
• subject.id_type: ruc, cedula, passport o foreign. No se retiene a consumidor final. Con foreign, indica kind (natural_person o company).
• subject.related_party: true si el proveedor es parte relacionada (por defecto false).
• Con subject.email, el RIDE y el XML se envían al proveedor cuando el SRI autoriza (por defecto en live; en test solo con send_email: true).

Las retenciones se consultan, descargan y reenvían igual que las facturas, en /v1/withholdings. Para ver las de un proveedor: GET /v1/withholdings?subject=1790012345001. Los webhooks son withholding.authorized, withholding.rejected y withholding.failed.

Por ahora no se admiten reembolsos, dividendos, compra de cajas de banano ni máquinas fiscales.