Create Credit Note

Creates, validates, and signs a new electronic credit note (nota de crédito) referencing a previously authorized invoice.

POST /v1/documents

This is the same endpoint as Create Invoice — the request body shape is selected by documentType. A credit note's body has no payments block and instead requires originalDocument (the invoice being credited) plus a motivo (reason).

The issuer must have document type 04 enabled — see Document Types.

Before submitting, check Get Credit Notes against the original document's access key to see how much of its total has already been credited — the API does not reject a credit note for exceeding the original's remaining balance, since SRI itself doesn't enforce that; it's a client-side guard.

Authentication

Authorization: Bearer <api-key>

Headers

Header	Required	Description
Authorization	Yes	Bearer API key
X-Issuer-Id	Yes	UUID of the issuing branch (from GET /v1/issuers). Identifies which branch and certificate to use.
Content-Type	Yes	application/json
Idempotency-Key	No	Unique string (max 255 chars) — see idempotency

Request body

{
  "documentType": "04",
  "issueDate": "05/04/2026",
  "buyer": {
    "idType": "05",
    "id": "1234567890",
    "name": "John Doe",
    "email": "[email protected]",
    "address": "Av. Amazonas 123"
  },
  "originalDocument": {
    "documentType": "01",
    "number": "001-001-000000027",
    "issueDate": "03/04/2026"
  },
  "motivo": "Devolución de mercadería por defecto de fabricación",
  "items": [
    {
      "mainCode": "PROD-001",
      "auxiliaryCode": "AUX-001",
      "description": "Web development service",
      "quantity": "1.00",
      "unitPrice": "100.00",
      "discount": "0.00",
      "taxes": [
        {
          "code": "2",
          "rateCode": "2",
          "rate": "15.00",
          "taxableBase": "100.00",
          "taxAmount": "15.00"
        }
      ]
    }
  ],
  "additionalInfo": [
    { "name": "Contract", "value": "CTR-2026-001" }
  ]
}

Field reference

Field	Type	Required	Description
documentType	string	Yes	Must be "04" for this body shape
issueDate	string	No	Date in DD/MM/YYYY format. Must be today's date — SRI rejects past and future dates. Defaults to today if omitted
buyer.idType	string	Yes	2-digit SRI identification type code (e.g. "05" = cedula, "04" = RUC)
buyer.id	string	Yes	Buyer identification number (max 20 chars)
buyer.name	string	Yes	Buyer full name or business name (max 300 chars)
buyer.email	string	Yes	Buyer email — RIDE and XML are sent here on authorization
buyer.address	string	No	Buyer address (max 300 chars)
originalDocument.documentType	string	Yes	SRI document type code of the document being credited (e.g. "01" for a factura)
originalDocument.number	string	Yes	Access-key-style number of the original document, format NNN-NNN-NNNNNNNNN
originalDocument.issueDate	string	Yes	Issue date of the original document, DD/MM/YYYY
motivo	string	Yes	Reason for the credit note (max 300 chars)
items	array	Yes	At least one item required
items[].mainCode	string	Yes	Product/service main code
items[].auxiliaryCode	string	No	Secondary code
items[].description	string	Yes	Description (max 300 chars)
items[].quantity	string	Yes	Numeric quantity
items[].unitPrice	string	Yes	Numeric unit price
items[].discount	string	No	Numeric discount amount
items[].taxes	array	Yes	At least one tax per item
items[].taxes[].code	string	Yes	SRI tax type code
items[].taxes[].rateCode	string	Yes	SRI tax rate code
items[].taxes[].rate	string	Yes	Tax rate percentage
items[].taxes[].taxableBase	string	Yes	Amount the tax is applied to
items[].taxes[].taxAmount	string	Yes	Calculated tax amount
additionalInfo	array	No	Key-value pairs included in the XML as campoAdicional

Response

201 Created — new document created. 200 OK — returned when the same Idempotency-Key + identical payload was already processed.

{
  "ok": true,
  "document": {
    "accessKey": "0504202604179234567800110010010000000271234567810",
    "documentType": "04",
    "sequential": "000000027",
    "status": "SIGNED",
    "issueDate": "05/04/2026",
    "total": "115.00",
    "email": {
      "status": "PENDING"
    }
  }
}

Idempotency

Include an Idempotency-Key header to make creation idempotent. Generate the key once per intended credit note and reuse it across retries:

• Same key + same payload → returns the existing document (no duplicate created)
• Same key + different payload → 409 Conflict

Errors

Code	Status	When
VALIDATION_FAILED	400	Request body fails field validation
DOCUMENT_TYPE_NOT_ENABLED	400	The issuer does not have document type 04 enabled — see Document Types
BAD_REQUEST	400	X-Issuer-Id header missing or malformed
UNAUTHORIZED	401	Missing or invalid API key, or environment mismatch (sandbox key targeting a production issuer or vice versa)
FORBIDDEN	403	The X-Issuer-Id issuer belongs to a different tenant
NOT_FOUND	404	The X-Issuer-Id issuer does not exist
CONFLICT	409	Idempotency key reused with a different payload
INTERNAL_ERROR	500	Unexpected server error