Notas de débito

POST /v1/debit-notes emite una nota de débito (XML 1.0.0): intereses, recargos u otros cargos que aumentan el valor de una factura ya emitida.

Solicitud

curl https://api.flashpi.com.ec/v1/debit-notes \
  -H "Authorization: Bearer $FLASHPI_API_KEY" \
  -H "Idempotency-Key: interest-PO-4812-oct" \
  -H "Content-Type: application/json" \
  -d '{
    "issuerId": "01a0fd6a-d098-76ca-b492-1bcb6505a7bd",
    "establishment": "001",
    "emissionPoint": "001",
    "issueDate": "2026-10-16",
    "customer": {
      "idType": "ruc",
      "id": "1790000000001",
      "name": "Supermercados La Pradera S.A.",
      "email": "compras@example.com"
    },
    "modifiedDocument": {
      "type": "invoice",
      "number": "001-001-000000123",
      "issueDate": "2026-10-15"
    },
    "reasons": [
      {
        "description": "Late payment interest",
        "amount": "10.00",
        "taxes": [{ "type": "vat", "rate": "15" }]
      }
    ],
    "payments": [{ "method": "other_financial_system", "amount": "11.50" }],
    "expectedTotal": "11.50"
  }'

Campo	Obligatorio	Notas
customer	Sí	El comprador de la factura modificada. No puede ser consumidor final. Las notas de débito no imprimen la dirección.
modifiedDocument	Sí	La factura que modifica: type (solo invoice, el valor por defecto), number e issueDate (igual o anterior a la de la nota de débito).
reasons	Sí	De 1 a 100 cargos, cada uno con su description, su amount antes de impuestos (hasta 2 decimales) y exactamente un IVA en taxes.
payments	Sí	Cómo se paga el débito; deben sumar el total.
expectedTotal	No	El total que esperas.

Igual que en las notas de crédito, las tarifas de IVA son las vigentes en la fecha de la factura modificada, y Flashpi no busca la factura: puede haberse emitido fuera de Flashpi. Las notas de débito no tienen descuento, propina ni ICE. Los campos que comparten todas las solicitudes funcionan igual que en todos los comprobantes.

Lo que calcula Flashpi

El IVA se calcula por tarifa sobre la suma de los valores de los motivos: el 15 % de 10.00 es 1.50, y el total es 11.50, que el pago debe igualar.

Respuesta

202 Accepted:

{
  "id": "01a1453c-bd7e-75aa-8168-50877b5f8557",
  "type": "debit_note",
  "environment": "test",
  "status": "processing",
  "issuerId": "01a0fd6a-d098-76ca-b492-1bcb6505a7bd",
  "establishment": "001",
  "emissionPoint": "001",
  "sequential": 4,
  "number": "001-001-000000004",
  "accessKey": "1610202605179000000000110010010000000041773058212",
  "issueDate": "2026-10-16",
  "xmlVersion": "1.0.0",
  "counterparty": { "id": "1790000000001", "name": "Supermercados La Pradera S.A." },
  "totals": {
    "subtotal": "10.00",
    "taxes": [{ "type": "vat", "rate": "15", "taxableBase": "10.00", "amount": "1.50" }],
    "total": "11.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-16T15:02:51.006Z",
  "updatedAt": "2026-10-16T15:02:51.006Z"
}

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

Errores

Respuesta	Cuándo
422 validation_failed	Por ejemplo payments amount_mismatch (deben sumar 11.50), reasons[0].taxes con más de un impuesto, o un consumidor final como cliente.
422 total_mismatch	expectedTotal es distinto del total calculado.
409 sequential_already_used, sequentials_exhausted	Consulta Secuenciales.