POST /v1/documents/credit-notes (body completo)

Scope: documents:write

Nota de crédito con control total del body. Úsalo cuando necesitas personalizar todos los campos. Admite ?async=true o X-Emit-Async: true.

Comprador y referencia al documento original

El comprador debe coincidir exactamente con la factura original.

Campo	Obligatorio	Descripción
`buyerIdType`, `buyerId`, `buyerName`	Sí	Deben ser los mismos que la factura original.
`issueDate`	Sí	`YYYY-MM-DD`. No puede ser futura.
`originalDocType`	Sí	01 Factura · 03 Liquidación · 05 Nota de débito. 2 dígitos.
`originalDocNumber`	Sí	Formato `001-001-000000001`.
`originalDocIssueDate`	Sí	Fecha emisión original. `YYYY-MM-DD`.
`originalAccessKey`	Sí	Clave de acceso 49 dígitos. La factura debe estar AUTHORIZED.
`reason`	Sí	Motivo. Máx. 300 chars.

Ítems (items[])

Al menos 1. Misma estructura que factura: description, quantity, unitPrice, taxes; opcionales mainCode, discount, additionalDetails. La nota de crédito no tiene el campo unit.

Totales y campos extra

Totales calculados automáticamente: totalWithoutTaxes, taxTotals, totalAmount. La NC no tiene totalDiscount ni tip. Opcionales: establishmentAddress, additionalInfo (máx. 15 entradas).

Reglas de negocio adicionales

Regla	Código
Factura original debe existir en la empresa	`ORIGINAL_DOCUMENT_NOT_FOUND`
Factura original debe estar AUTHORIZED	`ORIGINAL_DOCUMENT_NOT_AUTHORIZED`
`buyerId` debe coincidir con el original	`BUYER_ID_MISMATCH`
`buyerIdType` debe coincidir	`BUYER_ID_TYPE_MISMATCH`
`buyerName` debe coincidir	`BUYER_NAME_MISMATCH`

Errores HTTP

HTTP	error.code	Cuándo
401	`INVALID_API_KEY`	API Key inválida.
402	`TX_LIMIT_REACHED`	Límite de transacciones.
422	`FUTURE_ISSUE_DATE`	Fecha futura.
422	`INVALID_BUYER_ID`	Formato de identificación incorrecto.
422	`ORIGINAL_DOCUMENT_NOT_FOUND`	Factura original no encontrada.
422	`ORIGINAL_DOCUMENT_NOT_AUTHORIZED`	Factura no está AUTHORIZED.
422	`BUYER_ID_MISMATCH`	`buyerId` no coincide con el original.
422	`BUYER_ID_TYPE_MISMATCH`	`buyerIdType` no coincide con el original.
422	`BUYER_NAME_MISMATCH`	`buyerName` no coincide con el original.
422	`INCONSISTENT_TOTALS`	Totales no cuadran.

Ejemplo de respuesta 422 — BUYER_ID_MISMATCH

{
  "success": false,
  "error": {
    "code": "BUYER_ID_MISMATCH",
    "message": "buyerId de la nota de crédito (\"0991234560002\") no coincide con el de la factura original (\"0991234560001\").",
    "details": [{ "field": "buyerId" }]
  }
}

Ejemplo de respuesta 422 — ORIGINAL_DOCUMENT_NOT_AUTHORIZED

{
  "success": false,
  "error": {
    "code": "ORIGINAL_DOCUMENT_NOT_AUTHORIZED",
    "message": "La factura original no está autorizada (estado actual: REJECTED). Solo se pueden emitir notas de crédito sobre documentos autorizados por el SRI.",
    "details": [{ "field": "originalAccessKey" }]
  }
}

Ejemplo mínimo (body)

{
  "buyerIdType": "04",
  "buyerId": "0991234560001",
  "buyerName": "IMPORTADORA XYZ S.A.",
  "issueDate": "2026-03-08",
  "originalDocType": "01",
  "originalDocNumber": "001-001-000000002",
  "originalDocIssueDate": "2026-03-07",
  "originalAccessKey": "0703202601099123456000110010010000000024000000011",
  "reason": "Devolución total — producto defectuoso",
  "items": [
    {
      "description": "Servicio de desarrollo de software",
      "quantity": 10,
      "unitPrice": 80.00,
      "taxes": [{ "taxCode": "2", "rateCode": "2" }]
    }
  ]
}

Ejemplo en JavaScript

Nota de crédito con body completo contra POST /v1/documents/credit-notes:

const API_BASE_URL = 'https://live.faktur.com.ec';
const API_KEY = 'sk_...';
const API_SECRET = 'tu-secret';

const body = {
  buyerIdType: '04',
  buyerId: '0991234560001',
  buyerName: 'IMPORTADORA XYZ S.A.',
  issueDate: '2026-03-08',
  originalDocType: '01',
  originalDocNumber: '001-001-000000002',
  originalDocIssueDate: '2026-03-07',
  originalAccessKey: '0703202601099123456000110010010000000024000000011',
  reason: 'Devolución total — producto defectuoso',
  items: [
    {
      description: 'Servicio de desarrollo de software',
      quantity: 10,
      unitPrice: 80.00,
      taxes: [{ taxCode: '2', rateCode: '2' }]
    }
  ]
};

const response = await fetch(`${API_BASE_URL}/v1/documents/credit-notes`, {
  method: 'POST',
  headers: {
    'X-API-Key': API_KEY,
    'X-API-Secret': API_SECRET,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(body)
});

const json = await response.json();
if (json.success) {
  console.log('Nota de crédito:', json.data.accessKey, json.data.status);
} else {
  console.error('Error:', json.error?.code, json.error?.message);
}