Debit notes

POST /v1/debit-notes issues a debit note (nota de débito, XML 1.0.0): interest, fees or other charges that increase the amount of an invoice already issued.

Request

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"
  }'

Field	Required	Notes
customer	Yes	The buyer of the modified invoice. It cannot be a final consumer. Debit notes do not print the address.
modifiedDocument	Yes	The invoice it modifies: type (only invoice, the default), number and issueDate (on or before the debit note’s).
reasons	Yes	1 to 100 charges, each with a description, its amount before taxes (up to 2 decimals) and exactly one VAT in taxes.
payments	Yes	How the debit is paid; they must add up to the total.
expectedTotal	No	The total you expect.

As with credit notes, the VAT rates are the ones in force on the modified invoice’s date, and Flashpi does not look the invoice up: it may have been issued outside Flashpi. Debit notes have no discount, no tip and no ICE. The fields every request shares work as everywhere.

What Flashpi computes

The VAT is computed per rate on the summed amounts of the reasons: 15 % of 10.00 is 1.50, and the total is 11.50, which the payment must match.

Response

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"
}

With options.waitForAuthorization the answer can be 200 OK with the final status (Sync and async modes). The debit_note.authorized and debit_note.rejected webhooks report the SRI’s decision.

Errors

Answer	When
422 validation_failed	For example payments amount_mismatch (they must add up to 11.50), reasons[0].taxes with more than one tax, or a final consumer as the customer.
422 total_mismatch	expectedTotal differs from the computed total.
409 sequential_already_used, sequentials_exhausted	See Sequentials.