API Reference

Notas de débito

codDoc 05 — el VENDEDOR emite cargos adicionales sobre una factura ya emitida (intereses, penalizaciones, servicios extra). Estructura más simple que la NC: en lugar de líneas de productos, una lista de motivos (pares razon / valor) con un único codigoPorcentaje de IVA aplicado al total.

Eventos

Cada ND emite nota_debito.creada al encolarse y nota_debito.autorizada / nota_debito.rechazada / nota_debito.devuelta al resolverse en el SRI.

Emitir una nota de débito

POST /api/v1/notas-debito — Crea y encola una ND (async)

Body

Parámetro	Tipo	Descripción
`tipo_identificacion` required	string	Tipo de identificación del comprador (tabla SRI).
`identificacion` required	string	RUC/cédula/doc. del cliente.
`razon_social` required	string	Razón social del cliente.
`direccion` optional	string	Dirección del cliente.
`email` optional	string	Email del cliente (para enviar el RIDE).
`factura_id` optional	integer	Factura LOCAL a la que se aplica el cargo. Si lo envías, el backend copia automáticamente cliente y doc_sustento.
`cod_doc_sustento` optional	string	Código del doc. sustento. Default: '01' (factura).
`doc_sustento_numero` optional	string	Número del doc. sustento (15 dígitos). Obligatorio si NO envías factura_id.
`doc_sustento_fecha` optional	date	Fecha del doc. sustento (ISO 8601). Obligatorio si NO envías factura_id.
`tarifa_iva` required	integer	Tarifa de IVA aplicada al total: 0, 5 ó 15 (default 15).
`iva_codigo` optional	string	codigoPorcentaje del SRI (autoritativo; si se omite se deriva de tarifa_iva).
`motivos` required	array	Lista de cargos. Mínimo 1. Cada elemento: { razon (≤300 chars), valor (≥0) }.
`pagos` optional	array	Formas de pago (mismo shape que en la factura). Si se omite, se persiste un único pago '01' (efectivo) por el total.
`sucursal_id` optional	integer	Sucursal emisora. Se infiere del usuario si se omite.
`es_borrador` optional	boolean	Si true, guarda como BORRADOR sin encolar al SRI.
`idempotency_key` optional	string	Idempotencia (también header Idempotency-Key).

Respuesta (201 Created)

{
  "id": 8,
  "numero_comprobante": "001-001-000000003",
  "fecha_emision": "2026-07-05T11:02:00",
  "tipo_identificacion": "04",
  "identificacion": "0991234567001",
  "razon_social": "ACME S.A.",
  "cod_doc_sustento": "01",
  "doc_sustento_numero": "001-001-000000177",
  "doc_sustento_fecha": "2026-07-03T00:00:00",
  "tarifa_iva": 15,
  "iva_codigo": "4",
  "base_imponible": 80.0,
  "iva": 12.0,
  "total": 92.0,
  "estado": "PENDIENTE",
  "clave_acceso": null,
  "numero_autorizacion": null,
  "factura_id": 177,
  "motivos": [
    { "razon": "Interés por mora", "valor": 50.0 },
    { "razon": "Servicio extra",   "valor": 30.0 }
  ],
  "pagos": [ { "forma_pago": "01", "total": 92.0 } ]
}

import { Emitoo } from "emitoo";

const client = new Emitoo(); // lee la API key de EMITOO_API_KEY

const nd = await client.notasDebito.crear(
  {
    factura_id: 177,
    tarifa_iva: 15,
    motivos: [
      { razon: "Interés por mora", valor: 50.0 },
      { razon: "Servicio extra",   valor: 30.0 },
    ],
  },
  { idempotencyKey: "nd-90210" },
);

from emitoo import EmitooClient

client = EmitooClient()  # lee la API key de EMITOO_API_KEY

nd = client.notas_debito.crear(
    {
        # Factura externa — sin factura_id.
        "tipo_identificacion": "04",
        "identificacion": "0991234567001",
        "razon_social": "ACME S.A.",
        "doc_sustento_numero": "001-001-000000099",
        "doc_sustento_fecha": "2026-07-01T00:00:00",
        "tarifa_iva": 15,
        "motivos": [
            {"razon": "Interés por mora", "valor": 50.0},
            {"razon": "Servicio extra",   "valor": 30.0},
        ],
    },
    idempotency_key="nd-90210",
)

client, err := emitoo.New("") // lee la API key de EMITOO_API_KEY
if err != nil {
	log.Fatal(err)
}
ctx := context.Background()

nd, err := client.NotasDebito.Crear(ctx, emitoo.M{
	"factura_id": 177,
	"tarifa_iva": 15,
	"motivos": []emitoo.M{
		{"razon": "Interés por mora", "valor": 50.0},
		{"razon": "Servicio extra", "valor": 30.0},
	},
}, emitoo.WithIdempotencyKey("nd-90210"))
if err != nil {
	log.Fatal(err)
}

curl -X POST https://api.emitoo.io/api/v1/notas-debito \
  -H "X-API-Key: $EMITOO_API_KEY" \
  -H "Idempotency-Key: nd-90210" \
  -H "Content-Type: application/json" \
  -d '{
    "factura_id": 177,
    "tarifa_iva": 15,
    "motivos": [
      { "razon": "Interés por mora", "valor": 50.00 },
      { "razon": "Servicio extra",   "valor": 30.00 }
    ]
  }'

¿Cuándo se considera autorizada?

POST /api/v1/notas-debito responde al instante con la ND en PENDIENTE. Te avisamos por webhook con nota_debito.autorizada, o puedes hacer polling al endpoint de estado de más abajo.

Obtener una nota de débito

GET /api/v1/notas-debito/{id} — Detalle completo, con motivos y pagos

Consultar el estado

GET /api/v1/notas-debito/{id}/status — Solo el estado actual (más liviano, ideal para polling)

Reenviar al SRI

POST /api/v1/notas-debito/{id}/reenviar — Re-encola la ND al worker (sin body)

RIDE (PDF)

GET /api/v1/notas-debito/{id}/ride — Devuelve el PDF binario

Reenviar por email

POST /api/v1/notas-debito/{id}/email?to=opcional — Envía el RIDE (y el XML firmado) por email

Listado

GET /api/v1/notas-debito — Listado compacto (id, número, fecha, cliente, total, estado, ambiente)