Comprobantes de retención

POST /v1/withholdings emite un comprobante de retención (XML 2.0.0): el comprobante que un agente de retención entrega a un proveedor por el impuesto a la renta, el IVA o el ISD retenidos de un pago. Un comprobante cubre a un proveedor y uno o más de sus documentos.

Solicitud

curl https://api.flashpi.com.ec/v1/withholdings \
  -H "Authorization: Bearer $FLASHPI_API_KEY" \
  -H "Idempotency-Key: wh-001-002-000004567" \
  -H "Content-Type: application/json" \
  -d @withholding.json

withholding.json

{
  "issuerId": "01a0fd6a-d098-76ca-b492-1bcb6505a7bd",
  "establishment": "001",
  "emissionPoint": "001",
  "issueDate": "2026-10-15",
  "subject": {
    "idType": "ruc",
    "id": "0990000000001",
    "name": "Distribuidora del Pacífico S.A.",
    "relatedParty": false,
    "email": "facturacion@example.com"
  },
  "fiscalPeriod": "2026-10",
  "supportingDocuments": [
    {
      "taxSupportCode": "01",
      "documentTypeCode": "01",
      "number": "001-002-000004567",
      "issueDate": "2026-10-10",
      "authorizationNumber": "1010202601099000000000120010020000045677301928413",
      "subtotal": "1000.00",
      "total": "1150.00",
      "taxes": [{ "type": "vat", "rate": "15", "taxableBase": "1000.00" }],
      "withholdings": [
        { "tax": "income_tax", "code": "312", "taxableBase": "1000.00", "rate": "1.75" },
        { "tax": "vat", "code": "1", "taxableBase": "150.00" }
      ],
      "payments": [{ "method": "other_financial_system", "amount": "1150.00" }]
    }
  ],
  "expectedTotal": "62.50"
}

El sujeto retenido

Campo	Obligatorio	Notas
subject.idType, subject.id, subject.name	Sí	El proveedor. No puede ser consumidor final.
subject.relatedParty	Sí	Si el proveedor es parte relacionada.
subject.subjectType	Con foreign_id	individual (persona natural) o company (sociedad).
subject.email	No	Donde Flashpi envía el comprobante autorizado.
fiscalPeriod	No	AAAA-MM. Por defecto, el mes de la fecha de emisión.

Documentos de sustento

Cada elemento de supportingDocuments (de 1 a 50) es un documento del proveedor, normalmente su factura, con lo que le retienes:

Campo	Obligatorio	Notas
taxSupportCode	Sí	El código de sustento tributario del Catálogo ATS, tabla 5, como 01.
documentTypeCode	Sí	El código de tipo de comprobante del Catálogo ATS, tabla 4, como 01 para una factura.
number, issueDate	Sí	Su número y su fecha de emisión, igual o anterior a la del comprobante de retención.
authorizationNumber	No	Su número de autorización: 10, 37 o 49 dígitos (la clave de acceso de un comprobante electrónico).
accountingDate	No	Cuándo lo registraste en tu contabilidad.
subtotal, total	Sí	Su subtotal antes de impuestos y su total, tal como constan en el documento. Flashpi los copia; no los recalcula.
taxes	Sí	Su IVA: type vat, la rate vigente en su fecha de emisión y la taxableBase. amount es, por defecto, la base × la tarifa, redondeada.
withholdings	Sí	De 1 a 20 retenciones, ver abajo.
payments	Sí	Cómo se paga; los pagos deben sumar su total.
paymentResidence	No	local (por defecto) o foreign. Un pago al exterior requiere foreignPayment con el regime (general, tax_haven o preferential), el código de country del SRI y los indicadores de convenio.

Retenciones

Campo	Obligatorio	Notas
tax	Sí	income_tax (renta), vat (IVA) o isd.
code	Sí	El código de retención: el del Catálogo ATS para income_tax (por ejemplo 312), el de la TABLA 20 del SRI para vat (1 = 30 %, 2 = 70 %, 3 = 100 %) e isd.
taxableBase	Sí	La base sobre la que se aplica el porcentaje. En el IVA, es el valor del IVA del documento.
rate	Con income_tax	El porcentaje, con hasta 2 decimales. En vat e isd Flashpi lo toma del código, y una rate distinta se rechaza (rate_mismatch).
dividends	Con el código de sustento 10	paymentDate, corporateIncomeTax y profitFiscalYear.
bananaBoxes	Con los códigos de renta del banano	count y pricePerBox, para los códigos 338, 340, 341, 342, 342A y 342B.

Lo que calcula Flashpi

Cada valor retenido es la base imponible × el porcentaje, redondeado mitad hacia arriba a 2 decimales, y el total del comprobante es su suma:

Retención	Base × porcentaje	Retenido
Renta, código 312	1000.00 × 1.75 %	17.50
IVA, código 1 (30 %)	150.00 × 30 %	45.00
Total retenido		62.50

expectedTotal se compara con el total retenido.

Respuesta

202 Accepted. Los totals de un comprobante de retención solo tienen withheld:

{
  "id": "01a14167-168f-7c0b-b002-c22b0b25ee9c",
  "type": "withholding",
  "environment": "test",
  "status": "processing",
  "issuerId": "01a0fd6a-d098-76ca-b492-1bcb6505a7bd",
  "establishment": "001",
  "emissionPoint": "001",
  "sequential": 57,
  "number": "001-001-000000057",
  "accessKey": "1510202607179000000000110010010000000575296841018",
  "issueDate": "2026-10-15",
  "xmlVersion": "2.0.0",
  "counterparty": { "id": "0990000000001", "name": "Distribuidora del Pacífico S.A." },
  "totals": { "withheld": "62.50" },
  "authorization": { "number": null, "authorizedAt": null },
  "ride": { "status": "pending", "template": null, "generatedAt": null },
  "email": { "requested": true, "status": "queued", "deliveries": [], "warnings": [] },
  "sriMessages": [],
  "failure": null,
  "voidedAt": null,
  "createdAt": "2026-10-15T21:10:37.455Z",
  "updatedAt": "2026-10-15T21:10:37.455Z"
}

Con options.waitForAuthorization la respuesta puede ser 200 OK con el estado final (Modo síncrono y asíncrono). Los webhooks withholding.authorized y withholding.rejected informan la decisión del SRI.

Errores

Respuesta	Cuándo
422 validation_failed	Por ejemplo rate_mismatch en una retención de IVA con otro porcentaje, falta dividends o bananaBoxes donde los códigos los requieren, falta subject.subjectType con una identificación del exterior, o pagos que no suman el total del documento.
422 validation_failed con incompatible_issuer_profile	El número de contribuyente especial del emisor tiene más de los 5 caracteres que acepta un comprobante de retención.
422 total_mismatch	expectedTotal es distinto del total retenido.
409 sequential_already_used, sequentials_exhausted	Consulta Secuenciales.

Flashpi toma el porcentaje de las retenciones de IVA e ISD de su código, pero todavía no valida los códigos y porcentajes de renta contra el Catálogo ATS: usa la rate que envías. Los catálogos de retención cambian con las resoluciones del SRI, así que confirma con tu contador los códigos y porcentajes vigentes.