Ctrl K⌘K
Actualizado: Markdown Abrir en Claude Abrir en ChatGPT
En esta página

Nota de crédito POST

Emite una nota de crédito para devolver dinero, aplicar un descuento posterior o anular total o parcialmente una factura autorizada.

Un comprobante autorizado no se puede editar ni borrar. Cuando necesitas devolver dinero, conceder un descuento después de facturar o anular una venta, emites una nota de crédito que apunta a la factura original y dice cuánto se acredita al comprador.

Esta guía explica cómo identificar la factura que modificas, te da un ejemplo mínimo de devolución parcial listo para enviar y describe cada campo con las reglas que valida la API. El endpoint, las cabeceras, el secuencial automático y las reglas comunes a todos los tipos están en Comprobantes electrónicos.

Importante

Ambiente de pruebas: sin validez fiscal. Los ejemplos usan https://api-sandbox.mynexusapi.com y los datos de prueba.

La ruta de emisión fija el tipo 04. Si quieres comprobar el cuerpo antes de emitir, usa la ruta de validación, que aplica las mismas reglas y no consume cupo.

POST /v1/contribuyentes/{identificacion}/notas-credito
POST /v1/contribuyentes/{identificacion}/notas-credito/validar

No envíes infoTributaria.tipoDocumento. La validación se explica en Validar sin emitir.

Conceptos#

La factura a la que apunta la nota de crédito es el documento modificado o sustento. Además del valor que se acredita al comprador, la nota indica por qué se acredita.

  • Los valores de la nota son positivos: representan lo que devuelves o descuentas. No envíes importes negativos, porque la API responde 422.
  • El comprador es el mismo de la factura original.
  • La nota lleva sus propias líneas (detalles) con lo que se acredita, sus impuestos y sus totales. No lleva pagos.

Cuándo la emites#

Emite una nota de crédito en situaciones como estas:

  • Devolución parcial: el cliente devuelve uno de los productos que compró. La nota lleva solo la línea devuelta.
  • Devolución total o anulación de la venta: se revierte toda la factura. La nota lleva todas las líneas y su valor es igual al total de la factura.
  • Descuento posterior a la venta: un descuento por pronto pago o una bonificación por volumen que concedes después de facturar. La nota lleva una línea con el valor del descuento y su IVA.
  • Corrección de un precio cobrado de más: la nota acredita la diferencia.

Para cobrar un valor adicional sobre una factura, como intereses o recargos, usa una nota de débito, no una nota de crédito.

Referencia al documento modificado#

Con cuatro campos de info identificas la factura que modificas. Cópialos de tu registro de la factura original, porque la API no los busca ni los completa por ti.

Campo De dónde sale Formato Ejemplo
codDocModificado Tipo del comprobante original. Casi siempre una factura. Hasta 2 dígitos, completados con ceros a la izquierda. "01"
numDocModificado Número de la factura: estab-ptoEmi-secuencial. Es lo que se imprime en el RIDE y lo que devuelve numeroDocumento en el seguimiento. ddd-ddd-ddddddddd (3, 3 y 9 dígitos separados por guiones). "002-001-000000123"
fechaEmisionDocSustento fechaEmision de la factura original. dd/MM/yyyy. "01/10/2026"
totalDocumentoSustento importeTotal de la factura original. Opcional, pero recomendado. Número con 2 decimales. 115.00

El campo numDocModificado admite algunas variantes de formato:

  • Si un segmento tiene menos dígitos, la API lo completa con ceros: "2-1-123" se toma como "002-001-000000123". Te recomendamos enviar el formato completo para evitar dudas.
  • También se acepta sin guiones si tiene entre 10 y 15 dígitos, como "002001000000123".
  • Si envías solo el secuencial, como "123" o "000000123", la API lo rechaza, porque no supone el establecimiento ni el punto de emisión.

Si envías totalDocumentoSustento, la API comprueba que valorModificacion no lo supere. Si emites varias notas de crédito para una misma factura, controla en tu sistema que su suma no supere el total de la factura, porque la API no lleva el saldo acumulado de las notas anteriores.

Ejemplo mínimo#

Este ejemplo es una devolución parcial. De la factura 002-001-000000123 del 01/10/2026, con un total de 115.00, el cliente devuelve un servicio de 20.00 con IVA 15 %. Guarda el JSON como comprobante.json, porque lo usan los ejemplos de Envío.

{
  "origenReferencia": "MiERP",
  "referenciaExterna": "NOTACREDITO-2026-0001",
  "infoTributaria": {
    "ruc": "0123456789001",
    "estab": "002",
    "ptoEmi": "001"
  },
  "info": {
    "fechaEmision": "07/10/2026",
    "tipoIdentificacionComprador": "05",
    "identificacionComprador": "0123456789",
    "razonSocialComprador": "CONTRIBUYENTE DE PRUEBAS",
    "codDocModificado": "01",
    "numDocModificado": "002-001-000000123",
    "fechaEmisionDocSustento": "01/10/2026",
    "totalDocumentoSustento": 115.00,
    "totalSinImpuestos": 20.00,
    "totalConImpuestos": [
      {
        "codigo": "2",
        "codigoPorcentaje": "4",
        "tarifa": 15,
        "baseImponible": 20.00,
        "valor": 3.00
      }
    ],
    "valorModificacion": 23.00,
    "moneda": "DOLAR",
    "motivo": "DEVOLUCION PARCIAL DEL SERVICIO"
  },
  "detalles": [
    {
      "codigoInterno": "SERV-001",
      "descripcion": "DEVOLUCION SERVICIO DE MANTENIMIENTO",
      "cantidad": 1,
      "precioUnitario": 20.00,
      "descuento": 0,
      "precioTotalSinImpuesto": 20.00,
      "impuestos": [
        {
          "codigo": "2",
          "codigoPorcentaje": "4",
          "tarifa": 15,
          "baseImponible": 20.00,
          "valor": 3.00
        }
      ]
    }
  ]
}

La tabla muestra cómo se calcula cada total del ejemplo.

Campo Cálculo Valor
detalles[0].precioTotalSinImpuesto 1 x 20.00 - 0 20.00
detalles[0].impuestos[0].valor 20.00 x 15 / 100 3.00
totalConImpuestos[0] Suma de las líneas con IVA 15 % (4) base 20.00, valor 3.00
totalSinImpuestos Suma de precioTotalSinImpuesto 20.00
valorModificacion totalSinImpuestos + IVA + ICE = 20.00 + 3.00 23.00
Control de saldo 23.00 no supera totalDocumentoSustento (115.00) Correcto

valorModificacion ocupa en la nota de crédito el lugar de importeTotal: es el total que se acredita al comprador, con impuestos. Las líneas y los impuestos se calculan igual que en Cómo calcular los totales.

Envío#

Envía el comprobante.json del ejemplo mínimo con cualquiera de estos ejemplos. Todos usan como Idempotency-Key la misma referenciaExterna, NOTACREDITO-2026-0001, así que repetir el envío no emite otra nota.

curl -s -i -X POST \
  "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/notas-credito" \
  -H "X-Api-Key: $ECUAFACT_API_KEY" \
  -H "Idempotency-Key: NOTACREDITO-2026-0001" \
  -H "Content-Type: application/json" \
  -d @comprobante.json
# 202 Accepted -> sigue con GET /v1/operaciones/{idOperacion}
using System.Net.Http;
using System.Text;

string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!;
using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") };
http.DefaultRequestHeaders.Add("X-Api-Key", apiKey);

using var peticion = new HttpRequestMessage(HttpMethod.Post, "/v1/contribuyentes/0123456789001/notas-credito");
peticion.Headers.Add("Idempotency-Key", "NOTACREDITO-2026-0001");
peticion.Content = new StringContent(
    await File.ReadAllTextAsync("comprobante.json"), Encoding.UTF8, "application/json");

using HttpResponseMessage respuesta = await http.SendAsync(peticion);
Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}");
import json
import os
import requests

with open("comprobante.json", encoding="utf-8") as archivo:
    cuerpo = json.load(archivo)

r = requests.post(
    "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/notas-credito",
    headers={
        "X-Api-Key": os.environ["ECUAFACT_API_KEY"],
        "Idempotency-Key": "NOTACREDITO-2026-0001",
    },
    json=cuerpo,
    timeout=30,
)
print(r.status_code, r.text)
// Node.js 18 o superior. Guarda como emitir.mjs y ejecuta: node emitir.mjs
import { readFile } from 'node:fs/promises';

const res = await fetch(
  'https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/notas-credito',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.ECUAFACT_API_KEY,
      'Idempotency-Key': 'NOTACREDITO-2026-0001',
      'Content-Type': 'application/json'
    },
    body: await readFile('comprobante.json', 'utf8')
  });
console.log(res.status, await res.text());
<?php
$ch = curl_init('https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/notas-credito');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'X-Api-Key: ' . getenv('ECUAFACT_API_KEY'),
        'Idempotency-Key: NOTACREDITO-2026-0001',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => file_get_contents('comprobante.json'),
]);
$cuerpo = curl_exec($ch);
$estado = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $estado . ' ' . $cuerpo . PHP_EOL;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;
import java.nio.file.Path;

// Dentro de: public static void main(String[] args) throws Exception
HttpClient cliente = HttpClient.newHttpClient();
HttpRequest peticion = HttpRequest.newBuilder()
    .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/notas-credito"))
    .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY"))
    .header("Idempotency-Key", "NOTACREDITO-2026-0001")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(Files.readString(Path.of("comprobante.json"))))
    .build();
HttpResponse<String> respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString());
System.out.println(respuesta.statusCode() + " " + respuesta.body());
using Ecuafact.Sdk;

// client: EcuafactClient creado con tu API Key (ver SDK .NET)
// comprobante: NotaCreditoRequest con la nota de credito de esta pagina
EmisionResultado resultado = await client.EmitirAsync("0123456789001", comprobante, "NOTACREDITO-2026-0001");
Console.WriteLine($"Operacion {resultado.Admission.IdOperacion} / estado: {resultado.Admission.Estado}");
from ecuafact import EcuafactClient

# client: EcuafactClient creado con tu API Key (ver SDK Python)
# comprobante: NotaCreditoRequest con la nota de credito de esta pagina
resultado = client.emitir_en("0123456789001", comprobante, "NOTACREDITO-2026-0001")
print(f"Operacion {resultado.admission.id_operacion} / estado: {resultado.admission.estado}")
import { EcuafactClient } from "@ecuafact/sdk";

// client: EcuafactClient creado con tu API Key (ver SDK Node.js)
// comprobante: NotaCreditoRequest con la nota de credito de esta pagina
const resultado = await client.emitirEn("0123456789001", comprobante, "NOTACREDITO-2026-0001");
console.log(`Operacion ${resultado.admission.idOperacion} / estado: ${resultado.admission.estado}`);
<?php
use Ecuafact\Sdk\EcuafactClient;

// $client: EcuafactClient creado con tu API Key (ver SDK PHP)
// $comprobante: NotaCreditoRequest con la nota de credito de esta pagina
$resultado = $client->emitirEn('0123456789001', $comprobante, 'NOTACREDITO-2026-0001');
echo 'Operacion ' . $resultado->admission->idOperacion . ' / estado: ' . $resultado->admission->estado . PHP_EOL;
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EmisionResultado;

// client: EcuafactClient creado con tu API Key (ver SDK Java)
// comprobante: NotaCreditoRequest con la nota de credito de esta pagina
EmisionResultado resultado = client.emitirEn("0123456789001", comprobante, "NOTACREDITO-2026-0001");
System.out.println("Operacion " + resultado.admission().idOperacion() + " / estado: " + resultado.admission().estado());
# Resultado esperado: una fila con el estado recibido y el idOperacion de la emisión.
ecuafact emitir comprobante.json --entorno sandbox

Resultado esperado. La API responde 202 con estado en recibido, el codEstado 1001 o 1002 y un idOperacion.

Estructura del comprobante#

El cuerpo de la nota de crédito se organiza en bloques, y cada tabla describe uno.

Raíz#

Clave Tipo Obligatorio Regla
origenReferencia string Sí Nombre de tu sistema, de 1 a 64 caracteres entre letras y dígitos ASCII y - _ . : /.
referenciaExterna string Sí Tu número interno de la nota, de 1 a 128 caracteres con el mismo alfabeto.
infoTributaria object Sí Identidad del comprobante. Sus campos están en la tabla siguiente.
info object Sí Cabecera de la nota, que se describe más abajo.
detalles array Sí De 1 a 1000 líneas con lo que se acredita.
infoAdicional array No Hasta 15 objetos { "nombre", "valor" }, cada uno de 1 a 300 caracteres.

infoTributaria#

Campo Tipo Obligatorio Regla
ruc string Sí RUC completo del emisor, de 13 dígitos; en pruebas, 0123456789001.
estab string Sí Establecimiento de la nota, de hasta 3 dígitos. Se completa con ceros. Puede ser distinto del de la factura.
ptoEmi string Sí Punto de emisión de la nota, de hasta 3 dígitos. Se completa con ceros.
secuencial string No Hasta 9 dígitos. Omítelo y te asignamos el siguiente de la serie de notas de crédito, que es independiente de la serie de facturas.

info#

Campo Tipo Obligatorio Regla
fechaEmision string Sí Fecha de la nota, dd/MM/yyyy. Envía la fecha de hoy, porque el comprobante autorizado lleva la fecha del día en que se procesa.
dirEstablecimiento string No Hasta 300 caracteres.
tipoIdentificacionComprador string Sí 04 RUC, 05 cédula, 06 pasaporte u 08 identificación del exterior. Los valores están en Catálogos. 07, consumidor final, no se admite.
identificacionComprador string Sí La del comprador de la factura original. Con 04, 13 dígitos; con 05, 10 dígitos; con 06 y 08, hasta 20 caracteres.
razonSocialComprador string Sí Hasta 300 caracteres.
direccionComprador string No Hasta 300 caracteres.
telefono string No Hasta 40 caracteres.
correo string No Correo del comprador al que enviamos el comprobante, hasta 500 caracteres. Si lo omites, se toma un campo de infoAdicional llamado email o correo.
codDocModificado string Sí Tipo del documento modificado, normalmente "01". Se explica en Referencia al documento modificado.
numDocModificado string Sí ddd-ddd-ddddddddd.
fechaEmisionDocSustento string Sí Fecha de la factura original, dd/MM/yyyy.
totalDocumentoSustento number No importeTotal de la factura original. Si llega, valorModificacion no puede superarlo.
totalSinImpuestos number Sí Suma de detalles[].precioTotalSinImpuesto.
totalConImpuestos array Sí Una o dos filas, una por cada pareja codigo + codigoPorcentaje de las líneas, con baseImponible y valor sumados. tarifa es opcional.
valorModificacion number Sí totalSinImpuestos + IVA + ICE. Es el total acreditado.
moneda string Sí DOLAR o USD.
motivo string Sí Razón de la nota, como DEVOLUCION o DESCUENTO POR PRONTO PAGO, de hasta 300 caracteres. Los saltos de línea se convierten en espacios.

No envíes totalDescuento, propina, importeTotal ni pagos. Si los envías, aunque lleven 0, la API responde 422 con Campo no soportado en este contrato.

detalles[]#

En la nota de crédito, las líneas usan codigoInterno y codigoAdicional en lugar de codigoPrincipal y codigoAuxiliar.

Campo Tipo Obligatorio Regla
codigoInterno string Sí Código del bien o servicio, hasta 25 caracteres. Usa el mismo de la factura.
codigoAdicional string No Hasta 25 caracteres.
descripcion string Sí Hasta 300 caracteres.
cantidad number Sí Cantidad acreditada, mayor que 0, hasta 6 decimales.
precioUnitario number Sí Mayor o igual a 0, hasta 6 decimales, sin IVA.
descuento number Sí Importe en dólares, con 2 decimales como máximo. Envía 0 si no hay.
precioTotalSinImpuesto number Sí cantidad x precioUnitario - descuento, redondeado a 2 decimales.
impuestos array Sí Un IVA, con "2", y como máximo un ICE, con "3", cada uno con codigoPorcentaje, tarifa, baseImponible y valor. Usa la misma tarifa que tuvo la línea en la factura; las reglas están en Factura.
detallesAdicionales array No Hasta 3 objetos { "nombre", "valor" }.

Reglas de cálculo y validaciones#

Las líneas e impuestos siguen Cómo calcular los totales. Si una regla no se cumple, la API responde 422 con el codEstado 3002 (comprobante_invalido). Estos son los errores típicos de la nota de crédito:

Error típico Mensaje (en errores) Qué hacer
Enviar en numDocModificado solo el secuencial. $.info.numDocModificado: Indique establecimiento y punto de emision; no se infieren. Envía 002-001-000000123.
Enviar numDocModificado con otra cantidad de segmentos, como 002-001. $.info.numDocModificado: Use estab-pto-secuencial. Usa tres segmentos separados por guiones.
Enviar numDocModificado con letras o con segmentos demasiado largos. Solo se admiten digitos. / Longitud excedida. Usa como máximo 3, 3 y 9 dígitos.
Enviar la fecha del sustento en otro formato. $.info.fechaEmisionDocSustento: Use dd/MM/yyyy, como el SRI. Usa 01/10/2026.
La nota supera el total de la factura. El valor de la nota de credito no puede superar el total del documento que acredita. Revisa valorModificacion y totalDocumentoSustento.
Calcular mal valorModificacion. total no coincide con subtotal + IVA + ICE + propina. Calcula valorModificacion como totalSinImpuestos + IVA + ICE.
Enviar pagos, totalDescuento, propina o importeTotal. $.info.pagos: Campo no soportado en este contrato. Quita esos campos.
Usar codigoPrincipal en las líneas. $.detalles[0].codigoPrincipal: Campo no soportado en este contrato. Cambia a codigoInterno.
Identificar al comprador como consumidor final (07). ...requiere un contribuyente identificado. Identifica al comprador como en la factura original.
Enviar importes negativos. Numero fuera de rango. Envía valores positivos.
Falta motivo. $.info.motivo: Campo obligatorio. Explica la razón de la nota.
Calcular mal una línea. Subtotal del detalle no coincide con cantidad × precio − descuento. / Valor de impuesto no coincide con base y tasa. Recalcula la línea como en la factura.
Enviar un totalConImpuestos que no cuadra con las líneas. Base o valor de impuestos no coincide con detalles. Suma bases y valores por codigo + codigoPorcentaje.
totalSinImpuestos o el IVA no cuadran con las líneas. Totales no coinciden con detalles. Suma de nuevo las líneas.

Antes de emitir, te recomendamos comprobar en tu sistema que la factura modificada exista y esté autorizada, que el comprador coincida con el de la factura, que la fecha de la nota sea posterior a la de la factura y que la suma de varias notas no supere la factura. La API no hace esas comprobaciones; algunas puede hacerlas el SRI.

Más ejemplos#

Cada ejemplo es un cuerpo completo. Antes de enviarlo, cambia su referenciaExterna por una que no hayas usado y envía esa misma cadena como Idempotency-Key.

Devolución total de la factura#

Esta nota anula toda la factura 002-001-000000123, de 100.00 más 15.00 de IVA, es decir, 115.00. Su valorModificacion es igual a totalDocumentoSustento, lo que está permitido.

{
  "origenReferencia": "MiERP",
  "referenciaExterna": "NOTACREDITO-2026-0002",
  "infoTributaria": {
    "ruc": "0123456789001",
    "estab": "002",
    "ptoEmi": "001"
  },
  "info": {
    "fechaEmision": "07/10/2026",
    "tipoIdentificacionComprador": "05",
    "identificacionComprador": "0123456789",
    "razonSocialComprador": "CONTRIBUYENTE DE PRUEBAS",
    "codDocModificado": "01",
    "numDocModificado": "002-001-000000123",
    "fechaEmisionDocSustento": "01/10/2026",
    "totalDocumentoSustento": 115.00,
    "totalSinImpuestos": 100.00,
    "totalConImpuestos": [
      {
        "codigo": "2",
        "codigoPorcentaje": "4",
        "tarifa": 15,
        "baseImponible": 100.00,
        "valor": 15.00
      }
    ],
    "valorModificacion": 115.00,
    "moneda": "DOLAR",
    "motivo": "ANULACION DE LA VENTA"
  },
  "detalles": [
    {
      "codigoInterno": "SERV-001",
      "descripcion": "SERVICIO DE MANTENIMIENTO",
      "cantidad": 1,
      "precioUnitario": 100.00,
      "descuento": 0,
      "precioTotalSinImpuesto": 100.00,
      "impuestos": [
        {
          "codigo": "2",
          "codigoPorcentaje": "4",
          "tarifa": 15,
          "baseImponible": 100.00,
          "valor": 15.00
        }
      ]
    }
  ]
}

Descuento posterior por pronto pago#

El cliente pagó antes de tiempo y le concedes 5.00 de descuento sobre la misma factura. La nota lleva una línea de 5.00 con IVA 15 %, cuyo IVA es 5.00 x 15 / 100 = 0.75, así que valorModificacion es 5.00 + 0.75 = 5.75.

{
  "origenReferencia": "MiERP",
  "referenciaExterna": "NOTACREDITO-2026-0003",
  "infoTributaria": {
    "ruc": "0123456789001",
    "estab": "002",
    "ptoEmi": "001"
  },
  "info": {
    "fechaEmision": "07/10/2026",
    "tipoIdentificacionComprador": "05",
    "identificacionComprador": "0123456789",
    "razonSocialComprador": "CONTRIBUYENTE DE PRUEBAS",
    "codDocModificado": "01",
    "numDocModificado": "002-001-000000123",
    "fechaEmisionDocSustento": "01/10/2026",
    "totalDocumentoSustento": 115.00,
    "totalSinImpuestos": 5.00,
    "totalConImpuestos": [
      {
        "codigo": "2",
        "codigoPorcentaje": "4",
        "tarifa": 15,
        "baseImponible": 5.00,
        "valor": 0.75
      }
    ],
    "valorModificacion": 5.75,
    "moneda": "DOLAR",
    "motivo": "DESCUENTO POR PRONTO PAGO"
  },
  "detalles": [
    {
      "codigoInterno": "DESC-PP",
      "descripcion": "DESCUENTO POR PRONTO PAGO",
      "cantidad": 1,
      "precioUnitario": 5.00,
      "descuento": 0,
      "precioTotalSinImpuesto": 5.00,
      "impuestos": [
        {
          "codigo": "2",
          "codigoPorcentaje": "4",
          "tarifa": 15,
          "baseImponible": 5.00,
          "valor": 0.75
        }
      ]
    }
  ]
}

Respuesta#

La API responde 202 Accepted con este cuerpo:

{
  "estado": "recibido",
  "codEstado": 1001,
  "errores": [],
  "idOperacion": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",
  "urlEstado": "https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",
  "ambiente": 1,
  "tipoDocumento": "04",
  "numeroDocumento": "002-001-000000001",
  "referenciaExterna": "NOTACREDITO-2026-0001",
  "claveAcceso": null,
  "fhRecibido": "2026-11-16T10:15:00-05:00",
  "fhAutorizacion": null
}
Campo Tipo Descripción
estado string recibido: el comprobante pasó nuestras validaciones y lo aceptamos. No es una autorización. Un reintento con la misma Idempotency-Key y el mismo cuerpo responde con el mismo idOperacion y el estado actual de la operación. Normalmente el 202 trae recibido, pero si el resultado ya se conoce al responder, trae directamente el estado final (autorizado con 2001, rechazado con 3xxx o rechazo_configuracion con 4xxx), con su msgError y su detalle en errores. Decide siempre por estado y codEstado.
codEstado number 1001 si el comprobante todavía no tiene clave de acceso, o 1002 si ya la tiene. Acepta los dos valores.
errores array de string Viene siempre; en una emisión recibida es una lista vacía, y con un resultado final trae su detalle.
idOperacion string (UUID) Identificador de la operación. Guárdalo para el seguimiento.
urlEstado string URL completa del seguimiento, igual a la cabecera Location. Puedes llamarla tal como viene.
numeroDocumento string o null Número del comprobante con la forma estab-ptoEmi-secuencial, incluido el secuencial que te asignamos si no lo enviaste.
claveAcceso string o null Clave de acceso de 49 dígitos. Es null con el codEstado 1001; en ese caso la obtienes en el seguimiento o en el webhook. Con 1002 o con un resultado final ya viene en la respuesta.
fhRecibido string Fecha y hora en que recibimos la emisión, en ISO 8601 con zona horaria.

Los demás campos, ambiente, tipoDocumento, referenciaExterna y fhAutorizacion, tienen la misma forma del seguimiento de una operación, y el campo msgError solo aparece cuando el 202 ya trae un resultado final con error.

Un 202 significa que la nota quedó recibida, todavía no autorizada. Sigue la operación con GET /v1/operaciones/{idOperacion} o espera el webhook. Registra en tu sistema el crédito al cliente solo cuando su estado sea autorizado.

Estados de este endpoint#

Esta tabla reúne las respuestas que puedes recibir al emitir una nota de crédito.

codEstado HTTP Cuándo ocurre Qué hacer
1001 o 1002 202 La nota de crédito quedó recibida, o reintentaste con la misma Idempotency-Key y el mismo cuerpo. Guarda idOperacion y sigue la operación; un reintento trae el estado actual. No reenvíes con otros datos.
3003 (solicitud_invalida) 400 El JSON está mal formado, o la Idempotency-Key falta o no es válida. Corrige la petición.
3002 (comprobante_invalido) 422 La nota no cumple una regla; el detalle viene en errores. Corrige según la tabla de errores típicos. Consume 1 documento como intento.
3004 (comprobante_duplicado) 409 Ya existe una nota de crédito con ese número (estab-ptoEmi-secuencial) autorizada, pendiente o rechazada por el SRI. Consulta la existente. Si la anterior no se emitió (document.failed), puedes reenviar el mismo número con nueva Idempotency-Key y referenciaExterna; si la rechazó el SRI, emite con un secuencial nuevo (omite secuencial para que se asigne el siguiente).
3005 (conflicto_idempotencia) 409 Usaste la misma Idempotency-Key con otro cuerpo, o una referenciaExterna que ya usó otro comprobante. No cambies el cuerpo de un reintento. Para un comprobante nuevo, incluida la corrección de un rechazo, usa otra Idempotency-Key y otra referenciaExterna.
4004 (cupo_agotado) 429 Se agotó el cupo. Compra un paquete de documentos en el Portal del Cliente y no reintentes en bucle. Revisa Consumo.
3009 (credenciales_invalidas) 401 La API Key no es válida. Revisa la API Key.
3010 (ip_no_autorizada) 403 En producción, la IP no está registrada para tu API Key o no se pudo identificar. El ambiente de pruebas acepta cualquier IP. Registra tu IP en Cuenta > IP permitidas o llama sin proxies que oculten el origen.
3011 (acceso_denegado) 403 La nota de crédito no está habilitada para tu integración, o el ruc no es el del contribuyente. Revisa tiposComprobante en el contexto y el RUC enviado.
5005 (limite_solicitudes) 429 Superaste el límite de solicitudes por minuto. Espera los segundos que indica Retry-After y reintenta con la misma clave.

Todos los errores traen la misma forma de la respuesta 202, con msgError, el detalle en errores y idOperacion, urlEstado, numeroDocumento, claveAcceso y las fechas en null. El catálogo completo está en Errores.

Siguientes pasos#

No se pudo completar la operación. Recargar ✕

Conexión con el servidor

Restableciendo la conexión…

Intento 1 de 5.

No se pudo conectar. Revisa tu conexión y vuelve a intentarlo.

La sesión ya no está disponible. Recarga la página para continuar.

La sesión está en pausa. Puedes reanudarla para continuar.

No se pudo reanudar la sesión. Vuelve a intentarlo o recarga la página.

Al recargar se perderán los cambios que no hayas guardado.