Notas de débito

POST /api/v1/debit-notes/issue · scope documents:write

Una nota de débito aumenta el valor de una factura que el SRI ya autorizó: intereses por mora, gastos de envío no facturados, una diferencia de precio. En vez de líneas con cantidad y precio lleva motivos, cada uno con su importe y su IVA.

{
  "factura_modificada": { "secuencial": "001-001-000000123" },
  "motivo": "Intereses por mora",
  "motivos": [
    { "razon": "Interés por pago fuera de plazo", "valor": 12.50, "impuestos": [{ "codigo": "2", "codigo_porcentaje": "4" }] }
  ]
}

Campos de primer nivel

Campo	Obligatorio	Por defecto	Notas
factura_modificada	✅	—	{ "id" } o { "secuencial" }. Tiene que estar autorizada
motivo	✅	—	Motivo general, hasta 300 caracteres
motivos	✅	—	Un concepto por línea, con su valor sin impuestos
comprador	—	El de la factura	Solo si quieres otro correo o dirección
referencia_externa	—	—	Envíala siempre. Única por negocio entre notas de débito
fecha_emision	—	Hoy en Ecuador	No puede ser futura ni anterior a la factura
establecimiento	—	El de la clave o el del negocio	{ "codigo", "punto_emision" }
secuencial	—	El siguiente de la serie de notas de débito	Solo si controlas la numeración
totales	—	—	Si lo envías, se comprueba
enviar_email	—	true	Enviar el RIDE al comprador al autorizarse

factura_modificada y comprador funcionan exactamente como en la nota de crédito.

motivos

{
  "razon": "Interés por pago fuera de plazo",
  "valor": 12.50,
  "impuestos": [{ "codigo": "2", "codigo_porcentaje": "4" }]
}

Campo	Obligatorio	Notas
razon	✅	Hasta 255 caracteres; sale en el comprobante
valor	✅	Importe sin impuestos, mayor que 0
impuestos	—	IVA del concepto, como en una línea de factura. Sin él va con IVA 0 %

Los errores de impuestos apuntan al motivo: motivos[0].impuestos[0].valor.

Respuesta

202 Accepted. Igual que la nota de crédito, salvo que en lugar de items devuelve motivos y los totales no tienen descuento:

{
  "id": "b7c2e9f1-4a3d-4e8b-a1f0-2d9c6e5b7a44",
  "tipo": "nota_debito",
  "estado": "pendiente",
  "secuencial": "001-001-000000004",
  "clave_acceso": "2509202605099999999900110010010000000041234567818",
  "factura_modificada": { "id": "6f1e8a24-…", "secuencial": "001-001-000000123", "fecha_emision": "2026-09-12", "clave_acceso": "1209…" },
  "motivo": "Intereses por mora",
  "comprador": { "tipo_identificacion": "04", "identificacion": "1792060346001", "razon_social": "COMERCIAL ANDINA S.A.", "email": "facturas@andina.ec", "telefono": null, "direccion": null },
  "totales": { "total_sin_impuestos": 12.5, "iva": 1.88, "importe_total": 14.38 },
  "motivos": [
    { "razon": "Interés por pago fuera de plazo", "valor": 12.5, "impuestos": [ { "codigo": "2", "codigo_porcentaje": "4", "tarifa": 15.0, "base_imponible": 12.5, "valor": 1.88 } ] }
  ],
  "urls": { "detalle": "https://olympus.atharix.com/api/v1/debit-notes/b7c2e9f1-…", "pdf": null, "xml": null, "publica": null }
}

Ejemplo completo

curl

curl -X POST https://olympus.atharix.com/api/v1/debit-notes/issue \
  -H "X-API-Key: $OLYMPUS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ND-2026-0007" \
  -d '{
    "referencia_externa": "ND-2026-0007",
    "factura_modificada": { "secuencial": "001-001-000000123" },
    "motivo": "Intereses por mora",
    "motivos": [{
      "razon": "Interés por pago fuera de plazo",
      "valor": 12.50,
      "impuestos": [{ "codigo": "2", "codigo_porcentaje": "4" }]
    }]
  }'

Python

import os, requests

nota = requests.post(
    "https://olympus.atharix.com/api/v1/debit-notes/issue",
    headers={"X-API-Key": os.environ["OLYMPUS_API_KEY"], "Idempotency-Key": "ND-2026-0007"},
    json={
        "referencia_externa": "ND-2026-0007",
        "factura_modificada": {"secuencial": "001-001-000000123"},
        "motivo": "Intereses por mora",
        "motivos": [{
            "razon": "Interés por pago fuera de plazo",
            "valor": 12.50,
            "impuestos": [{"codigo": "2", "codigo_porcentaje": "4"}],
        }],
    },
    timeout=30,
)
nota.raise_for_status()
print(nota.json()["totales"]["importe_total"])

Node

const response = await fetch("https://olympus.atharix.com/api/v1/debit-notes/issue", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.OLYMPUS_API_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": "ND-2026-0007",
  },
  body: JSON.stringify({
    referencia_externa: "ND-2026-0007",
    factura_modificada: { secuencial: "001-001-000000123" },
    motivo: "Intereses por mora",
    motivos: [{
      razon: "Interés por pago fuera de plazo",
      valor: 12.5,
      impuestos: [{ codigo: "2", codigo_porcentaje: "4" }],
    }],
  }),
});
const nota = await response.json();
console.log(nota.totales.importe_total);

PHP

$client = new \GuzzleHttp\Client(['base_uri' => 'https://olympus.atharix.com/api/v1/']);
$response = $client->post('debit-notes/issue', [
    'headers' => ['X-API-Key' => getenv('OLYMPUS_API_KEY'), 'Idempotency-Key' => 'ND-2026-0007'],
    'json' => [
        'referencia_externa' => 'ND-2026-0007',
        'factura_modificada' => ['secuencial' => '001-001-000000123'],
        'motivo' => 'Intereses por mora',
        'motivos' => [[
            'razon' => 'Interés por pago fuera de plazo',
            'valor' => 12.50,
            'impuestos' => [['codigo' => '2', 'codigo_porcentaje' => '4']],
        ]],
    ],
]);
$nota = json_decode((string) $response->getBody(), true);
echo $nota['totales']['importe_total'];