Glosario
Terminos y convenciones de nombres de la API. Usa estos nombres al integrar y al reportar un caso.
| Termino | Significado |
|---|---|
| API Key | Clave de tu integracion. Se envia en la cabecera X-Api-Key. |
| Ambiente | Entorno de trabajo: pruebas (sandbox) o produccion. Cada ambiente tiene su propia URL. |
| Contribuyente | Persona natural o juridica habilitada para emitir o recibir comprobantes. |
| Identificacion | Valor del contribuyente que se usa en la ruta. El RUC completo de 13 digitos va en infoTributaria.ruc. |
| Emisor | Contribuyente que emite el comprobante. |
| Receptor / contraparte | Contribuyente que recibe el comprobante (comprador, proveedor o sujeto retenido). |
| Comprobante electronico | Documento fiscal (factura, nota de credito o debito, guia, retencion o liquidacion) emitido y transmitido al SRI. |
| Clave de acceso | Identificador unico de 49 digitos del comprobante. Lo asigna la plataforma; no lo envias. |
| Establecimiento / punto de emision | Serie donde se numera un comprobante (estab y ptoEmi, 3 digitos cada uno). |
| Secuencial | Numero consecutivo del comprobante dentro de la serie (9 digitos). |
| Operacion | El proceso de emision de un comprobante. Se identifica con idOperacion. |
| Seguimiento | Consultar el estado de la operacion (GET /v1/operaciones/{id}) o recibirlo por webhook. |
| Autorizacion | Resultado del SRI: no_disponible, pendiente, autorizado o error. |
| Idempotency-Key | Cabecera que identifica una intencion de emision y evita duplicados al reintentar. |
| Cupo | Documentos disponibles para tu integracion (plan mas paquetes comprados). |
| Retencion | Impuesto que el emisor descuenta al proveedor y acredita al SRI. |
| Comprobante de sustento | Documento de referencia que respalda una retencion o una nota. |
| RIDE | Representacion grafica del comprobante (el PDF con el detalle y el codigo de autorizacion). |
| Webhook | Aviso HTTP que la plataforma te envia cuando una operacion cambia de estado. |
Evento (eventType) |
El tipo de cambio notificado por un webhook (document.authorized, document.rejected, etc.). |
hayMas |
Campo de los listados que indica si quedan mas resultados despues de la pagina actual. |
| SRI | Servicio de Rentas Internas del Ecuador, autoridad fiscal. |
Terminos fijos#
Usa siempre el mismo termino para el mismo concepto. No inventes sinonimos. Estos son los nombres canonicos: comprobante, emision, operacion, autorizacion, claveAcceso, RIDE, contribuyente, ambiente.
No llames X a Y#
| No uses | Usa | Por que |
|---|---|---|
| "recibido" como sinonimo de autorizado | "recibido" (aun sin resultado) y "autorizado" (resultado fiscal) | Un comprobante recibido no esta autorizado. |
| "factura" para cualquier comprobante | "comprobante" o el tipo (factura, nota de credito, retencion...) | Hay seis tipos con reglas propias. |
| "SRI" para el comprobante o para la API | "el SRI" solo es la autoridad; el comprobante es "comprobante" | Evita confusion entre autoridad y documento. |
| "credenciales" (plural) para varios RUC | "una credencial por integracion" | Una credencial cubre todos sus RUC habilitados. |
| "estado fiscal" generico | estado (ciclo de envio) y estadoAutorizacion (resultado del SRI) |
Son dos cosas distintas. |
Lo mismo aplica a errores y microcopy: un codigo, un mensaje y una accion por caso.