Emitir comprobante de retención

POST

/v1/withholdings

curl --request POST \
  --url https://api.chaski.ec/v1/withholdings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --data '{ "issuer": "example", "emission_point": "example", "external_ref": "example", "subject": { "id_type": "ruc", "id": "example", "name": "example", "email": "[email protected]", "kind": "natural_person", "related_party": true }, "fiscal_period": "example", "documents": [ { "support_code": "example", "type": "example", "number": "example", "issue_date": "example", "accounting_date": "example", "authorization_number": "example", "foreign_payment": { "regime": "general", "country": "example", "double_taxation_treaty": true, "subject_to_withholding": true, "preferential_regime": true }, "subtotal": "example", "total": "example", "taxes": [ { "type": "iva", "rate": "0", "base": "example", "amount": "example" } ], "withholdings": [ { "tax": "income", "code": "example", "base": "example", "rate": "example" } ], "payments": [ { "method": "no_financial_system", "amount": "example" } ] } ], "additional_info": { "additionalProperty": "example" }, "metadata": { "additionalProperty": "example" }, "send_email": true }'

Comprobante de retención (07), esquema 2.0.0. El emisor es el agente de retención y subject el proveedor al que se le retiene (no puede ser consumidor final; con id_type: "foreign" hay que indicar kind). Cada documento de sustento lleva sus impuestos, sus retenciones y sus pagos, que deben sumar total. El valor retenido se calcula (base × porcentaje). En IVA el porcentaje sale del código (1 30 %, 2 70 %, 3 100 %, 9 10 %, 10 20 %, 11 50 %, 7 y 8 0 %) y la base no puede pasar del IVA del documento; en renta e ISD el porcentaje es obligatorio y en renta la base no puede pasar del subtotal. Responde 202 con status: "pending" y se notifica con withholding.authorized o withholding.rejected. En producción consume cuota igual que una factura (402 quota_exceeded).

Authorizations

• apiKey

Parameters

Header Parameters

Idempotency-Key

required

string

<= 255 characters

Una clave única por petición (por ejemplo un UUID). Vale 24 h: reintentar con la misma clave y el mismo body devuelve la misma respuesta.

Request Body^required

Media typeapplication/json

object

issuer

required

string

emission_point

required

string

/^\d{3}-\d{3}$/

external_ref

string

>= 1 characters <= 255 characters

subject

required

object

id_type

required

string

Allowed values: ruc cedula passport foreign

id

required

string

>= 1 characters <= 20 characters

name

required

string

>= 1 characters <= 300 characters

email

string format: email

/^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$/

kind

string

Allowed values: natural_person company

related_party

boolean

fiscal_period

string

/^\d{4}-\d{2}$/

documents

required

Array<object>

>= 1 items <= 50 items

object

support_code

required

string

/^\d{2}$/

type

required

string

/^\d{2,3}$/

number

required

string

/^\d{3}-\d{3}-\d{9}$/

issue_date

required

string

/^\d{4}-\d{2}-\d{2}$/

accounting_date

string

/^\d{4}-\d{2}-\d{2}$/

authorization_number

string

/^\d{10,49}$/

foreign_payment

object

regime

required

string

Allowed values: general tax_haven preferential

country

required

string

/^\d{3,4}$/

double_taxation_treaty

required

boolean

subject_to_withholding

required

boolean

preferential_regime

boolean

subtotal

required

string

/^\d+(\.\d+)?$/

total

required

string

/^\d+(\.\d+)?$/

taxes

required

Array

>= 1 items <= 20 items

One of:

object

object

type

required

string

Allowed value: iva

rate

required

string

Allowed values: 0 5 15 exempt not_subject

base

required

string

/^\d+(\.\d+)?$/

amount

required

string

/^\d+(\.\d+)?$/

object

object

type

required

string

Allowed values: ice irbpnr

rate_code

required

string

/^\d{1,4}$/

rate

required

string

/^\d+(\.\d+)?$/

base

required

string

/^\d+(\.\d+)?$/

amount

required

string

/^\d+(\.\d+)?$/

withholdings

required

Array<object>

>= 1 items <= 20 items

object

tax

required

string

Allowed values: income iva isd

code

required

string

>= 1 characters <= 5 characters

base

required

string

/^\d+(\.\d+)?$/

rate

string

/^\d+(\.\d+)?$/

payments

required

Array<object>

>= 1 items <= 20 items

object

method

required

string

Allowed values: no_financial_system debt_compensation debit_card electronic_money prepaid_card credit_card other_financial_system endorsement

amount

string

/^\d+(\.\d+)?$/

additional_info

object

key

additional properties

string

<= 300 characters

metadata

object

key

additional properties

string

<= 500 characters

send_email

boolean

Responses

202

OK

Media typeapplication/json

object

id

required

string

status

required

string

Allowed values: pending received authorized rejected failed

environment

required

string

Allowed values: test live

issuer

required

string

emission_point

required

string

number

required

string

access_key

required

Clave de acceso de 49 dígitos

string

issue_date

required

string format: date

/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$/

fiscal_period

required

string

subject

required

object

id

required

string

name

required

string

email

required

string | null

documents

required

Array<object>

object

type

required

string

number

required

string

issue_date

required

string format: date

/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$/

total

required

string

withholdings

required

Array<object>

object

tax

required

string

Allowed values: income iva isd

code

required

string

base

required

string

rate

required

string

amount

required

string

total_withheld

required

string

total_withheld

required

string

external_ref

required

string | null

metadata

required

object

key

additional properties

string

sri_messages

required

Array<object>

object

code

required

string

type

required

string

message

required

string

additional_info

string

authorized_at

required

Any of:

string

string format: date-time

/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$/

null

null

created_at

required

string format: date-time

/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$/

Example

{
  "id": "wht_01jbx3k9q2f8m4tn6vwz0yh5ce",
  "status": "pending",
  "environment": "test",
  "emission_point": "001-003",
  "number": "001-003-000000009",
  "fiscal_period": "2026-11",
  "documents": [
    {
      "type": "01",
      "number": "001-001-000000123",
      "withholdings": [
        {
          "tax": "income",
          "code": "312",
          "rate": "1.75"
        }
      ]
    }
  ]
}

400

Petición inválida

Media typeapplication/json

object

error

required

object

code

required

string

message

required

string

field

string

key

additional properties

Example

{
  "error": {
    "code": "invalid_request"
  }
}

401

Falta la API key o no es válida

Media typeapplication/json

object

error

required

object

code

required

string

message

required

string

field

string

key

additional properties

Example

{
  "error": {
    "code": "invalid_request"
  }
}

402

Cuota de comprobantes agotada (quota_exceeded)

Media typeapplication/json

object

error

required

object

code

required

string

message

required

string

field

string

key

additional properties

Example

{
  "error": {
    "code": "invalid_request"
  }
}

403

Sin permiso (cuenta suspendida, emisor no habilitado en producción, límite del plan…)

Media typeapplication/json

object

error

required

object

code

required

string

message

required

string

field

string

key

additional properties

Example

{
  "error": {
    "code": "invalid_request"
  }
}

422

No se puede procesar (certificado vencido, Idempotency-Key reutilizada…)

Media typeapplication/json

object

error

required

object

code

required

string

message

required

string

field

string

key

additional properties

Example

{
  "error": {
    "code": "invalid_request"
  }
}

429

Demasiadas peticiones

Media typeapplication/json

object

error

required

object

code

required

string

message

required

string

field

string

key

additional properties

Example

{
  "error": {
    "code": "invalid_request"
  }
}