En esta página
Guía de remisión POST
Emite una guía de remisión, el comprobante que respalda el traslado de mercadería y la acompaña mientras está en tránsito.
La guía de remisión documenta quién transporta la mercadería, desde dónde sale, a quién se entrega y qué bienes lleva.
Esta guía te da un ejemplo mínimo listo para enviar, explica los límites de este comprobante y describe cada campo con las reglas que valida la API. El endpoint, las cabeceras 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.
Emites la guía de remisión con este endpoint. Para validar el mismo cuerpo sin
emitir, usa POST /v1/contribuyentes/{identificacion}/guias-remision/validar;
la validación aplica las mismas reglas y no consume cupo, como se explica en
Validar sin emitir.
POST /v1/contribuyentes/{identificacion}/guias-remision
Cabeceras: X-Api-Key, Idempotency-Key, Content-Type: application/json
Conceptos#
- Transportista: la persona o empresa que conduce el vehículo. Puede ser tu propio chofer o un tercero. Se identifica con su tipo de identificación, número, razón social y la placa del vehículo.
- Destinatario: quien recibe la mercadería. Lleva su identificación,
dirección de entrega, el motivo del traslado y la lista de bienes (
detalles). - Fechas de transporte: el periodo en que la mercadería está en tránsito.
La fecha de inicio (
fechaIniTransporte) es también la fecha de emisión de la guía; por eso esta guía no llevafechaEmision.
Los demás términos, como RUC, establecimiento, secuencial, clave de acceso o RIDE, están explicados en el Glosario.
Cuándo la emites#
Emites la guía antes de que la mercadería salga. Estos son los casos habituales:
- Entregas a un cliente: llevas a su bodega lo que le vendiste.
- Trasladas mercadería entre tus propios establecimientos, por ejemplo de la matriz a una sucursal.
- Envías mercadería a consignación o a reparación, o la devuelves a un proveedor.
La guía no cobra nada: no lleva precios, impuestos, totales ni formas de pago. Si además vendes la mercadería, emite también la Factura.
Límites de la guía de remisión#
La API aplica estos límites a la guía de remisión.
| Límite | Qué significa para ti |
|---|---|
| Un destinatario por guía | destinatarios lleva exactamente un elemento. Si repartes a varios clientes, emite una guía por cada uno. |
| Destinatario con cédula o RUC | identificacionDestinatario tiene 10 dígitos (cédula) o 13 (RUC). Un pasaporte o una identificación del exterior se rechaza. |
| Sin documento de sustento por destinatario | No se admiten los campos que asocian el destinatario a una factura (codDocSustento, numDocSustento, numAutDocSustento, fechaEmisionDocSustento). Si los envías, la API responde 422 con Campo no soportado en este contrato. |
| Sin importes | Los detalles solo describen bienes y cantidades. |
Antes de empezar#
- Una API Key de pruebas en la variable de entorno
ECUAFACT_API_KEY. Si todavía no tienes una, crea tu sandbox. - En el ambiente de pruebas puedes llamar desde cualquier IP. En producción, la IP desde la que llamas debe estar registrada para tu API Key, como se explica en Autenticación.
- El valor
identificacionde tu contribuyente, que obtienes conGET /v1/contexto. En los ejemplos es0123456789001. - El tipo
06habilitado para ese contribuyente, es decir, que aparezca entiposComprobantedel contexto. - Los datos del transportista, la placa, las fechas del traslado y el destinatario.
Ejemplo mínimo#
Este ejemplo representa el traslado de dos productos desde la bodega del emisor
hasta la bodega de un cliente, del 7 al 8 de octubre de 2026. Guarda el JSON
como comprobante.json, porque lo usan los ejemplos de Envío.
{
"origenReferencia": "MiERP",
"referenciaExterna": "GR-2026-0001",
"infoTributaria": {
"ruc": "0123456789001",
"estab": "001",
"ptoEmi": "001",
"secuencial": "000000000"
},
"info": {
"dirPartida": "BODEGA PRINCIPAL DE PRUEBAS",
"razonSocialTransportista": "TRANSPORTISTA DE PRUEBAS",
"tipoIdentificacionTransportista": "05",
"rucTransportista": "0123456789",
"fechaIniTransporte": "07/10/2026",
"fechaFinTransporte": "08/10/2026",
"placa": "PBA0001"
},
"destinatarios": [
{
"identificacionDestinatario": "0123456789001",
"razonSocialDestinatario": "CLIENTE DE PRUEBAS",
"dirDestinatario": "BODEGA DEL CLIENTE DE PRUEBAS",
"motivoTraslado": "VENTA",
"codEstabDestino": "001",
"ruta": "QUITO - GUAYAQUIL",
"detalles": [
{
"codigoInterno": "PROD-001",
"descripcion": "CAJA DE PRODUCTO DE PRUEBAS",
"cantidad": 10
},
{
"codigoInterno": "PROD-002",
"descripcion": "REPUESTO DE PRUEBAS",
"cantidad": 2.5
}
]
}
],
"infoAdicional": [
{
"nombre": "email",
"valor": "cliente@example.com"
}
]
}
Con "secuencial": "000000000" te asignamos el siguiente número de la serie
001-001 de guías de remisión, y omitir el campo tiene el mismo efecto.
Antes de enviarla, comprueba que la fecha de fin no sea anterior a la de inicio, que cada cantidad sea mayor que 0 y que haya un solo destinatario con al menos un detalle.
Envío#
Envía el comprobante.json del ejemplo mínimo con cualquiera de estos
ejemplos. Todos usan como Idempotency-Key la misma referenciaExterna,
GR-2026-0001.
curl -s -i -X POST \
"https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/guias-remision" \
-H "X-Api-Key: $ECUAFACT_API_KEY" \
-H "Idempotency-Key: GR-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/guias-remision");
peticion.Headers.Add("Idempotency-Key", "GR-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/guias-remision",
headers={
"X-Api-Key": os.environ["ECUAFACT_API_KEY"],
"Idempotency-Key": "GR-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/guias-remision',
{
method: 'POST',
headers: {
'X-Api-Key': process.env.ECUAFACT_API_KEY,
'Idempotency-Key': 'GR-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/guias-remision');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'X-Api-Key: ' . getenv('ECUAFACT_API_KEY'),
'Idempotency-Key: GR-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/guias-remision"))
.header("X-Api-Key", System.getenv("ECUAFACT_API_KEY"))
.header("Idempotency-Key", "GR-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 System.Text.Json;
using Ecuafact.Sdk;
using Ecuafact.Sdk.Contracts;
var client = EcuafactClient.Create(new EcuafactClientOptions
{
BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"),
ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!
});
GuiaRemisionRequest comprobante = JsonSerializer.Deserialize<GuiaRemisionRequest>(
await File.ReadAllTextAsync("comprobante.json"))!;
EmisionResultado resultado = await client.EmitirAsync("0123456789001", comprobante, "GR-2026-0001");
Console.WriteLine($"Operacion {resultado.Admission.IdOperacion} / estado: {resultado.Admission.Estado}");
import json
import os
from ecuafact import GuiaRemisionRequest, EcuafactClient, EcuafactClientOptions
client = EcuafactClient(EcuafactClientOptions(
base_address="https://api-sandbox.mynexusapi.com/",
api_key=os.environ["ECUAFACT_API_KEY"],
))
with open("comprobante.json", encoding="utf-8") as archivo:
comprobante = GuiaRemisionRequest.model_validate(json.load(archivo))
resultado = client.emitir_en("0123456789001", comprobante, "GR-2026-0001")
print(f"Operacion {resultado.admission.id_operacion} / estado: {resultado.admission.estado}")
// Node.js 18 o superior. Guarda como emitir-sdk.mjs y ejecuta: node emitir-sdk.mjs
import { readFile } from 'node:fs/promises';
import { EcuafactClient } from '@ecuafact/sdk';
const client = new EcuafactClient({
baseAddress: 'https://api-sandbox.mynexusapi.com/',
apiKey: process.env.ECUAFACT_API_KEY
});
const comprobante = JSON.parse(await readFile('comprobante.json', 'utf8'));
const resultado = await client.emitirGuiaRemisionEn('0123456789001', comprobante, 'GR-2026-0001');
console.log(`Operacion ${resultado.admission.idOperacion} / estado: ${resultado.admission.estado}`);
<?php
use Ecuafact\Sdk\EcuafactClient;
use Ecuafact\Sdk\EcuafactClientOptions;
$client = new EcuafactClient(new EcuafactClientOptions(
baseAddress: 'https://api-sandbox.mynexusapi.com/',
apiKey: getenv('ECUAFACT_API_KEY'),
));
// $comprobante: GuiaRemisionRequest con la estructura de esta pagina (como armarlo: SDK PHP).
$resultado = $client->emitirEn('0123456789001', $comprobante, 'GR-2026-0001');
echo 'Operacion ' . $resultado->admission->idOperacion . ' / estado: ' . $resultado->admission->estado . PHP_EOL;
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.EmisionResultado;
import com.ecuafact.sdk.contracts.GuiaRemisionRequest;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.nio.file.Files;
import java.nio.file.Path;
// Dentro de: public static void main(String[] args) throws Exception
EcuafactClient client = new EcuafactClient(
EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY")));
GuiaRemisionRequest comprobante = new ObjectMapper()
.readValue(Files.readString(Path.of("comprobante.json")), GuiaRemisionRequest.class);
EmisionResultado resultado = client.emitirEn("0123456789001", comprobante, "GR-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 guía.
ecuafact emitir comprobante.json --entorno sandbox
Si repites exactamente la misma solicitud, con la misma Idempotency-Key y el
mismo cuerpo, por ejemplo tras un timeout, la API no crea otra guía. Responde
202 con el mismo idOperacion y el estado actual de la operación.
Estructura del comprobante#
El cuerpo de la guía de remisión se organiza en bloques, y cada tabla describe uno.
Raíz#
| Campo | Tipo | Obligatorio | Regla |
|---|---|---|---|
origenReferencia |
string | Sí | Nombre de tu sistema de origen, de hasta 64 caracteres entre letras y dígitos ASCII y - _ . : /. |
referenciaExterna |
string | Sí | Identificador estable del documento en tu sistema, de hasta 128 caracteres con el mismo alfabeto. Repítelo igual en cada reintento. |
infoTributaria |
object | Sí | Identidad del comprobante, descrita en la tabla infoTributaria. |
info |
object | Sí | Datos del traslado y del transportista. Su detalle está en la tabla info. |
destinatarios |
array | Sí | Exactamente un destinatario. Su detalle está en la tabla destinatarios. |
infoAdicional |
array | No | Hasta 15 objetos {nombre, valor}. Su detalle está en la tabla infoAdicional. |
No envíes detalles en la raíz, porque van dentro del destinatario, ni
motivos o docsSustento; si lo haces, la API responde 422 con
Campo no soportado en este contrato. Tampoco envíes claveAcceso, ambiente,
tipoEmision, version ni formato, porque la API no los admite.
infoTributaria#
| Campo | Tipo | Obligatorio | Regla |
|---|---|---|---|
ruc |
string | Sí | RUC del emisor, de 5 a 13 dígitos. Debe ser igual a la identificacion de la ruta; por ejemplo, 0123456789001. |
estab |
string | Sí | Código del establecimiento que emite, de hasta 3 dígitos. Se completa con ceros, así que "1" se toma como "001". |
ptoEmi |
string | Sí | Código del punto de emisión, de hasta 3 dígitos. Se completa con ceros. |
secuencial |
string | No | Si lo omites o envías "000000000", te asignamos el siguiente número de la serie, que forman estab, ptoEmi, el tipo 06 y el ambiente. Si envías un número de hasta 9 dígitos, entre 1 y 999999999, usamos ese número. |
info#
| Campo | Tipo | Obligatorio | Regla |
|---|---|---|---|
dirPartida |
string | Sí | Dirección desde donde sale la mercadería, hasta 300 caracteres. |
razonSocialTransportista |
string | Sí | Nombre o razón social del transportista, hasta 300 caracteres. |
tipoIdentificacionTransportista |
string | Sí | 04 RUC, 05 cédula, 06 pasaporte o 08 identificación del exterior. Los valores están en Catálogos. |
rucTransportista |
string | Sí | Identificación del transportista. Aunque el nombre del campo dice RUC, sigue al tipo: con 04, 13 dígitos; con 05, 10 dígitos; con otros tipos, hasta 20 caracteres. |
fechaIniTransporte |
string | Sí | Inicio del traslado, dd/MM/yyyy. Es también la fecha de emisión de la guía. |
fechaFinTransporte |
string | Sí | Fin del traslado, dd/MM/yyyy. Igual o posterior a fechaIniTransporte. |
placa |
string | Sí | Placa del vehículo, hasta 20 caracteres. |
dirEstablecimiento |
string | No | Dirección del establecimiento emisor, hasta 300 caracteres. |
telefono |
string | No | Teléfono del destinatario, hasta 40 caracteres. |
correo |
string | No | Correo del destinatario al que enviamos el comprobante, hasta 500 caracteres. Si lo omites, se usa el infoAdicional llamado email o correo. |
La guía no usa fechaEmision, moneda, pagos ni ningún total, y si los
envías, la API responde 422 con Campo no soportado en este contrato.
destinatarios#
| Campo | Tipo | Obligatorio | Regla |
|---|---|---|---|
identificacionDestinatario |
string | Sí | Cédula de 10 dígitos o RUC de 13. No necesitas enviar el tipo, porque lo deducimos del largo. |
razonSocialDestinatario |
string | Sí | Nombre o razón social, hasta 300 caracteres. |
dirDestinatario |
string | Sí | Dirección de entrega, hasta 300 caracteres. |
motivoTraslado |
string | Sí | Por qué se traslada la mercadería, como VENTA, TRASLADO ENTRE ESTABLECIMIENTOS o DEVOLUCION, hasta 300 caracteres. |
codEstabDestino |
string | No | Código del establecimiento de destino del destinatario, de 3 dígitos. |
ruta |
string | No | Recorrido del traslado, hasta 300 caracteres. No puede ser solo espacios. |
docAduaneroUnico |
string | No | Número del documento aduanero, si el traslado lo requiere, hasta 20 caracteres. |
detalles |
array | Sí | De 1 a 1000 bienes. Su detalle está en la tabla destinatarios[].detalles. |
destinatarios[].detalles#
| Campo | Tipo | Obligatorio | Regla |
|---|---|---|---|
codigoInterno |
string | Sí | Código del bien en tu sistema, hasta 25 caracteres. |
codigoAdicional |
string | No | Código adicional del bien. |
descripcion |
string | Sí | Descripción del bien, hasta 300 caracteres. |
cantidad |
number | Sí | Cantidad trasladada, mayor que 0. |
detallesAdicionales |
array | No | Hasta 3 objetos {nombre, valor}, como el lote o la serie. |
codigoPrincipal y codigoAuxiliar son de la factura, y si los envías, la API
responde 422 con Campo no soportado en este contrato. Tampoco envíes precioUnitario, descuento,
precioTotalSinImpuesto ni impuestos.
infoAdicional#
| Campo | Tipo | Obligatorio | Regla |
|---|---|---|---|
nombre |
string | Sí | Nombre del dato, hasta 300 caracteres. |
valor |
string | Sí | Valor del dato, hasta 300 caracteres. |
Estos datos aparecen en el RIDE, el PDF del comprobante.
Validaciones#
Si alguna regla falla, la API responde 422 con el codEstado 3002 (comprobante_invalido), y errores
describe la regla y, cuando aplica, el campo, como en $.destinatarios: Lista vacia, invalida o demasiado extensa.
Un 422 consume 1 documento como intento, pero no usa un número de la serie, así que corrige el
dato y reenvía.
| Regla | Ejemplo de incumplimiento |
|---|---|
destinatarios tiene exactamente un elemento. |
Dos destinatarios en la misma guía. |
identificacionDestinatario tiene 10 o 13 dígitos. |
Un pasaporte AB123456. |
fechaFinTransporte no es anterior a fechaIniTransporte. |
Inicio 08/10/2026, fin 07/10/2026. |
Las fechas van en dd/MM/yyyy. |
2026-10-07. |
Cada detalle tiene codigoInterno, descripcion y cantidad mayor que 0. |
cantidad: 0, que responde Guía admite cantidades y no importes ni impuestos. |
rucTransportista coincide con su tipo. |
Tipo 04 con 10 dígitos. |
| Solo se envían los campos de la guía. | Enviar info.fechaEmision o info.pagos. |
Respuesta#
Si la solicitud es válida, la API responde 202 Accepted. La guía quedó recibida, pero todavía no tiene el resultado del SRI.
{
"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": "06",
"numeroDocumento": "001-001-000000001",
"referenciaExterna": "GR-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, porque lo necesitas 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.
La respuesta trae además estas cabeceras:
| Cabecera | Descripción |
|---|---|
Location |
La misma URL completa que urlEstado. |
X-Correlation-Id |
Identificador de correlación de la solicitud. Cítalo al pedir soporte. |
Después de recibirla, sigue estos pasos:
- Guarda
idOperacionjunto a la guía en tu sistema. - Consulta
GET /v1/operaciones/{idOperacion}, como se explica en Seguimiento de una operación, o espera el webhook. - Cuando su
estadoseaautorizado, la operación trae laclaveAccesoreal de 49 dígitos y puedes descargar el RIDE para que viaje con la mercadería. Si esrechazadoorechazo_configuracion, elcodEstadote dice la causa yerroresel detalle; corrígela y emite de nuevo con unaIdempotency-Keynueva y unareferenciaExternanueva. Si elcodEstadoes 3001 (rechazo_sri), usa además el secuencial automático, como se explica en Reintentos y duplicados.
Estados de este endpoint#
Esta tabla reúne las respuestas que puedes recibir al emitir una guía de remisión.
codEstado |
HTTP | Cuándo ocurre | Qué hacer |
|---|---|---|---|
| 1001 o 1002 | 202 | La guía 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 | Falta Idempotency-Key o no es ASCII de hasta 128 caracteres, o el JSON o el XML está mal formado. |
Corrige la solicitud según errores y reenvía. |
3002 (comprobante_invalido) |
422 | Falta un campo obligatorio, un campo tiene formato inválido o no se cumple una regla de la guía (destinatarios, fechas, campos de otro tipo, campo desconocido, ruc que no corresponde a la ruta). |
Corrige el campo indicado en errores. Consume 1 documento como intento. |
3006 (cuerpo_excedido) |
413 | El cuerpo supera 2 MiB. | Reduce el número de detalles o de infoAdicional. |
3009 (credenciales_invalidas) |
401 | La API Key falta o no es válida. | Revisa X-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 revisa proxies entre tu sistema y la API. |
3011 (acceso_denegado) |
403 | El contribuyente de la ruta o el tipo 06 no están habilitados. |
Verifica GET /v1/contexto; si falta el tipo, solicita habilitarlo. |
3004 (comprobante_duplicado) |
409 | Ya existe una guía 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. |
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. |
5005 (limite_solicitudes) |
429 | Superaste el límite de solicitudes por minuto. | Espera lo que indique Retry-After y reintenta con la misma Idempotency-Key. |
4004 (cupo_agotado) |
429 | Se agotó el cupo de documentos. | Revisa GET /v1/consumo y compra un paquete. |
5002 (servicio_no_disponible) |
503 | El servicio no está disponible temporalmente. | Reintenta con la misma Idempotency-Key y el mismo cuerpo. |
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.
Atención
Ante un timeout, reintenta con la misma Idempotency-Key y el mismo cuerpo. Cambiar la clave o la referenciaExterna puede emitir dos guías para el mismo traslado.
Siguientes pasos#
- Seguimiento de una operación: consulta si el SRI autorizó la guía y obtiene su clave de acceso.
- Descarga del RIDE: obtiene el PDF que acompaña a la mercadería.
- Factura: emite la venta de la mercadería que trasladas.
- Webhooks: recibe el resultado sin consultar periódicamente.