API Reference

Notas de crédito

codDoc 04 — corrige o anula una factura ya emitida. Si envías factura_id, Emitoo toma automáticamente el cliente y el documento de sustento de la factura local; si lo omites, debes enviar doc_sustento_numero y doc_sustento_fecha a mano (caso de factura externa).

Eventos

Por cada nota de crédito Emitoo emite nota_credito.creada al encolar y nota_credito.autorizada / nota_credito.rechazada / nota_credito.devuelta al resolverse el SRI. Suscríbelos desde la sección de webhooks.

Emitir una nota de crédito

POST /api/v1/notas-credito — Crea y encola una NC (async)

Body

Parámetro	Tipo	Descripción
`tipo_identificacion` required	string	Tipo de identificación del comprador (tabla SRI: 04 RUC, 05 cédula, 06 pasaporte, 07 consumidor final, 08 id. del exterior).
`identificacion` required	string	RUC/cédula/doc. del cliente que recibe la NC.
`razon_social` required	string	Razón social del cliente.
`direccion` optional	string	Dirección del cliente (impresa en el RIDE).
`email` optional	string	Email del cliente (se usa para reenviar el RIDE).
`factura_id` optional	integer	Factura LOCAL a la que se aplica la NC. Si lo envías, el backend copia automáticamente cliente y doc_sustento; puedes omitir doc_sustento_numero/fecha.
`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; acepta con o sin guiones). Obligatorio si NO envías factura_id.
`doc_sustento_fecha` optional	date	Fecha emisión del doc. sustento (ISO 8601). Obligatorio si NO envías factura_id.
`motivo` required	string	Razón de la NC (ej. 'Devolución por producto defectuoso'). Máx 300 caracteres.
`detalles` required	array	Líneas del comprobante. Mínimo 1. Misma forma que en factura (codigoPrincipal, descripcion, cantidad, precioUnitario, descuento, tarifaIva, ivaCodigo).
`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. Default: false.
`idempotency_key` optional	string	Idempotencia (también header Idempotency-Key): reintentos con la misma key devuelven la MISMA NC.

Respuesta (201 Created)

{
  "id": 12,
  "numero_comprobante": "001-001-000000002",
  "fecha_emision": "2026-07-05T10:34:12",
  "tipo_identificacion": "04",
  "identificacion": "0991234567001",
  "razon_social": "ACME S.A.",
  "motivo": "Devolución por producto defectuoso",
  "doc_sustento_numero": "001-001-000000177",
  "doc_sustento_fecha": "2026-07-03T10:12:34",
  "subtotal_0": 0.0,
  "subtotal_15": 75.0,
  "iva": 11.25,
  "total": 86.25,
  "estado": "PENDIENTE",
  "clave_acceso": null,
  "numero_autorizacion": null,
  "factura_id": 177,
  "detalles": [ { "codigo_principal": "LIC-1", "descripcion": "Licencia mensual", "cantidad": 1, "precio_unitario": 75.0 } ]
}

import { Emitoo } from "emitoo";

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

const nc = await client.notasCredito.crear(
  {
    // Vinculamos a la factura local — el cliente se copia automáticamente.
    factura_id: 177,
    motivo: "Devolución por producto defectuoso",
    detalles: [
      { codigo_principal: "LIC-1", descripcion: "Licencia mensual",
        cantidad: 1, precio_unitario: 75.0, tarifa_iva: 15 },
    ],
  },
  { idempotencyKey: "dev-90210" },
);

from emitoo import EmitooClient

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

nc = client.notas_credito.crear(
    {
        # Factura externa — sin factura_id, doc_sustento a mano.
        "tipo_identificacion": "04",
        "identificacion": "0991234567001",
        "razon_social": "ACME S.A.",
        "doc_sustento_numero": "001-001-000000099",
        "doc_sustento_fecha": "2026-07-01T00:00:00",
        "motivo": "Devolución parcial",
        "detalles": [
            {"codigo_principal": "LIC-1", "descripcion": "Licencia mensual",
             "cantidad": 1, "precio_unitario": 75.0, "tarifa_iva": 15},
        ],
    },
    idempotency_key="dev-90210",
)

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

// Vinculamos a la factura local — el cliente se copia automáticamente.
nc, err := client.NotasCredito.Crear(ctx, emitoo.M{
	"factura_id": 177,
	"motivo":     "Devolución por producto defectuoso",
	"detalles": []emitoo.M{
		{"codigo_principal": "LIC-1", "descripcion": "Licencia mensual",
			"cantidad": 1, "precio_unitario": 75.0, "tarifa_iva": 15},
	},
}, emitoo.WithIdempotencyKey("dev-90210"))
if err != nil {
	log.Fatal(err)
}

curl -X POST https://api.emitoo.io/api/v1/notas-credito \
  -H "X-API-Key: $EMITOO_API_KEY" \
  -H "Idempotency-Key: dev-90210" \
  -H "Content-Type: application/json" \
  -d '{
    "factura_id": 177,
    "motivo": "Devolución por producto defectuoso",
    "detalles": [
      { "codigo_principal": "LIC-1", "descripcion": "Licencia mensual",
        "cantidad": 1, "precio_unitario": 75.00, "tarifa_iva": 15 }
    ]
  }'

¿Cómo averiguo cuándo quedó autorizada?

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

Obtener una nota de crédito

GET /api/v1/notas-credito/{id} — Detalle completo, con líneas

Consultar el estado

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

Reenviar al SRI

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

RIDE (PDF)

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

Reenviar por email

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

Listado

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