{ "openapi": "3.1.0", "jsonSchemaDialect": "https://spec.openapis.org/oas/3.1/dialect/base", "info": { "title": "API de Golem Facturación", "version": "1.0.0", "summary": "Emisión, consulta y descarga de comprobantes electrónicos del SRI de Ecuador.", "description": "API de Golem para emitir facturas, notas de crédito y comprobantes de retención electrónicos desde tu propio\nsistema. Golem calcula los totales, asigna el número y la clave de acceso, firma el XML con la firma electrónica\nde tu empresa, lo envía al SRI y te devuelve la autorización. También puedes consultar el estado de cualquier\ncomprobante de tu empresa y descargar el XML autorizado y el RIDE en PDF.\n\n## Autenticación\nCada solicitud lleva la cabecera `Authorization: Bearer `. Los tokens son de la empresa y se crean en la\naplicación, en **Cuenta > API e integraciones** (solo administradores). El token se muestra una sola vez al\ncrearlo; Golem guarda solo su huella. Nunca envíes el token en la URL ni en el cuerpo.\n\n## Ambientes\nEl token decide el ambiente del SRI: los tokens `glm_prueba_…` emiten y consultan en el ambiente de pruebas, y\nlos tokens `glm_prod_…` en producción. Un token solo ve los comprobantes de su ambiente. En pruebas los\ncomprobantes no tienen validez tributaria y el correo no se envía al receptor sino a un buzón de Golem.\n\n## Créditos\nCada comprobante emitido consume un crédito del saldo de la empresa, también en pruebas. Si el comprobante\ntermina devuelto, no autorizado o con error, el crédito vuelve al saldo. Sin créditos, la emisión responde\n`402 SIN_CREDITOS`; las consultas y descargas siguen disponibles.\n\n## Emisión y tiempos\nDespués de guardar el comprobante, Golem lo firma y lo envía al SRI de inmediato, y espera la respuesta hasta\n12 segundos. Si llega a un estado final responde `201`; si no, responde `202` con estado `EN_PROCESO` y el\ncomprobante sigue su proceso: consulta `GET /comprobantes/{claveAcceso}` más tarde. La cabecera\n`Prefer: respond-async` pide la respuesta inmediata con `202`. Configura en tu cliente HTTP un tiempo de espera\nde al menos 30 segundos para las emisiones.\n\nDesde 2026 el SRI exige transmitir cada comprobante en el momento de su emisión: la fecha de emisión es la de\nhoy (hora de Ecuador); se acepta la del día anterior solo por diferencias de zona horaria.\n\n## Reintentos seguros\nEnvía la cabecera `Idempotency-Key` en cada emisión. Si repites la solicitud con la misma clave y el mismo\ncuerpo dentro de 24 horas, Golem no crea otro comprobante ni consume otro crédito: responde con el comprobante\noriginal. La misma clave con otro cuerpo responde `409`. La clave vale por empresa y por ambiente: la misma\nclave en pruebas y en producción son dos operaciones distintas.\n\n## Sincronización\nPara conocer los cambios de estado sin consultar cada comprobante, lista con `cambiadoDesde` (el\n`fechaActualizacion` más reciente que ya procesaste): la respuesta viene ordenada del cambio más antiguo al más\nreciente.\n\n## Errores\nLos errores usan el código HTTP real y un cuerpo `{\"error\": {...}}` con un `codigo` estable, un `mensaje` en\nespañol, el `campo` afectado (o `null`), los `detalles` por campo y el `requestId` de la solicitud. Además de\nlas respuestas de cada operación, cualquier ruta puede responder `404 RUTA_NO_ENCONTRADA`,\n`405 METODO_NO_PERMITIDO` o `406 FORMATO_NO_ACEPTADO` con el mismo formato. Los mensajes del SRI de un\ncomprobante van en su lista `mensajes`, no en el error.\n\n## Límites\nPor token: 60 solicitudes por minuto en total, de ellas hasta 20 emisiones por minuto (emitir y reprocesar),\n10 reenvíos de correo por minuto y 20 consultas de RUC por minuto. Por empresa: 40 emisiones por minuto sumando\ntodos sus tokens. Las rutas públicas (catálogos y especificación) admiten 60 solicitudes por minuto por\ndirección IP. Las solicitudes sin token (o con el token en la URL) y las que traen un token no válido tienen\nlímites propios por dirección IP, que nunca bloquean a un token válido. El límite se cuenta al recibir la\nsolicitud, antes de validarla: una emisión rechazada por validación (`400`, `422`), por tipo de contenido\n(`415`) o por formato de respuesta (`406`) también consume el límite de emisión. Al superar un límite se responde `429` con `Retry-After`. Cada respuesta informa el límite en\nlas cabeceras `RateLimit-Limit`, `RateLimit-Remaining` y `RateLimit-Reset`. Si tu operación necesita más,\nescribe a info@golem.ec.\n\n## Formato\nJSON en UTF-8 con nombres en camelCase. Fechas como `yyyy-MM-dd` (el período fiscal como `yyyy-MM`); instantes\nen ISO 8601 con la zona de Ecuador (`-05:00`). Montos en dólares con 2 decimales; el precio unitario, sin IVA,\nadmite hasta 4 decimales y la cantidad hasta 2. En todo el contrato `tipo` es una enumeración legible\n(`FACTURA`) y `codDoc` el código del SRI (`01`). Las respuestas pueden sumar campos nuevos sin cambiar de\nversión: tu integración debe ignorar los campos y los valores de enumeración que no conozca. Las solicitudes,\nen cambio, rechazan los campos desconocidos.\n", "termsOfService": "https://golem.ec/terminos/", "license": { "name": "Uso sujeto a los términos y condiciones de Golem", "url": "https://golem.ec/terminos/" }, "contact": { "name": "Soporte de Golem", "email": "info@golem.ec", "url": "https://golem.ec/desarrolladores/" } }, "externalDocs": { "description": "Documentación del API con guías y ejemplos", "url": "https://golem.ec/desarrolladores/" }, "servers": [ { "url": "https://api.golem.ec/v1", "description": "API de Golem (el token decide el ambiente del SRI)" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Emisión", "description": "Crear facturas, notas de crédito y comprobantes de retención.", "externalDocs": { "url": "https://golem.ec/desarrolladores/facturas/" } }, { "name": "Consulta", "description": "Estado, listado y descargas de los comprobantes de la empresa del token.", "externalDocs": { "url": "https://golem.ec/desarrolladores/consulta-y-descargas/" } }, { "name": "Acciones", "description": "Reprocesar un comprobante pendiente o devuelto y reenviar su correo.", "externalDocs": { "url": "https://golem.ec/desarrolladores/estados/" } }, { "name": "Empresa", "description": "Datos de la empresa del token, establecimientos, puntos de emisión y créditos.", "externalDocs": { "url": "https://golem.ec/desarrolladores/empresa/" } }, { "name": "RUC", "description": "Consulta del catastro de RUC del SRI.", "externalDocs": { "url": "https://golem.ec/desarrolladores/ruc/" } }, { "name": "Catálogos", "description": "Códigos del SRI que usa el API. No requieren token.", "externalDocs": { "url": "https://golem.ec/desarrolladores/catalogos/" } }, { "name": "Especificación", "description": "Esta especificación OpenAPI." } ], "paths": { "/comprobantes/facturas": { "post": { "tags": [ "Emisión" ], "operationId": "emitirFactura", "summary": "Emitir una factura", "description": "Crea una factura (código 01) en el punto de emisión indicado, calcula subtotales, IVA y total, asigna el\nsecuencial y la clave de acceso, la firma y la envía al SRI.\n\n- `establecimiento` y `puntoEmision` son los códigos de 3 dígitos. Si los omites, se usa el punto por\n defecto del token.\n- Envía el precio unitario **sin IVA**, con hasta 4 decimales, y la cantidad con hasta 2. Si tu sistema\n maneja precios con IVA incluido, la guía de facturas explica cómo convertirlos. El IVA de cada ítem se\n indica con `iva` (porcentaje) o con `codigoIva` (código del SRI). Para *no objeto de IVA* usa\n `codigoIva: \"6\"` y para *exento* `\"7\"`.\n- Indica el pago con `formaPago` (una sola forma por el total) o con `pagos` (varias formas; deben sumar el\n total).\n- Si envías `totalEsperado`, Golem compara su cálculo con ese valor y rechaza la factura si difieren en más\n de 0.01.\n- Si un ítem usa el código de un producto de tu catálogo con control de inventario y no hay existencias,\n la factura no se emite (`422 SIN_STOCK`).\n- Envía siempre `Idempotency-Key`: si la conexión se corta, repite la solicitud con la misma clave.\n", "externalDocs": { "url": "https://golem.ec/desarrolladores/facturas/" }, "x-limites": [ "general", "emision" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/Prefer" }, { "$ref": "#/components/parameters/XRequestIdEntrada" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacturaSolicitud" }, "examples": { "minima": { "$ref": "#/components/examples/FacturaSolicitudMinima" }, "completa": { "$ref": "#/components/examples/FacturaSolicitudCompleta" }, "consumidorFinal": { "$ref": "#/components/examples/FacturaSolicitudConsumidorFinal" } } } } }, "responses": { "201": { "$ref": "#/components/responses/ComprobanteCreado" }, "202": { "$ref": "#/components/responses/ComprobanteEnProceso" }, "400": { "$ref": "#/components/responses/SolicitudInvalida" }, "401": { "$ref": "#/components/responses/NoAutenticado" }, "402": { "$ref": "#/components/responses/SinCreditos" }, "403": { "$ref": "#/components/responses/Prohibido" }, "409": { "$ref": "#/components/responses/ConflictoIdempotencia" }, "413": { "$ref": "#/components/responses/CuerpoDemasiadoGrande" }, "415": { "$ref": "#/components/responses/TipoContenidoNoSoportado" }, "422": { "$ref": "#/components/responses/ReglaNoCumplida" }, "429": { "$ref": "#/components/responses/LimiteExcedido" }, "500": { "$ref": "#/components/responses/ErrorInterno" }, "503": { "$ref": "#/components/responses/NoDisponible" } } } }, "/comprobantes/notas-credito": { "post": { "tags": [ "Emisión" ], "operationId": "emitirNotaCredito", "summary": "Emitir una nota de crédito", "description": "Crea una nota de crédito (código 04) que modifica una factura.\n\n- Si la factura se emitió en Golem, basta su `claveAcceso` en `documentoModificado`: Golem toma de ella el\n número, la fecha y los datos del cliente, verifica que esté autorizada, que las tarifas de IVA sean las de\n la factura y que la suma de sus notas de crédito no supere su total.\n- Si la factura se emitió fuera de Golem, envía `codDoc`, `numero` y `fechaEmision` del documento y los\n datos del `cliente`.\n- El receptor debe estar identificado: no se emite una nota de crédito a consumidor final\n (`9999999999999`), tampoco si la factura modificada fue a consumidor final (`422 CLIENTE_NO_PERMITIDO`).\n- Las tarifas de IVA admitidas son las vigentes a la fecha de la factura modificada (por ejemplo, 12 % para\n facturas anteriores al 1 de abril de 2024).\n", "externalDocs": { "url": "https://golem.ec/desarrolladores/notas-credito/" }, "x-limites": [ "general", "emision" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/Prefer" }, { "$ref": "#/components/parameters/XRequestIdEntrada" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotaCreditoSolicitud" }, "examples": { "facturaDeGolem": { "$ref": "#/components/examples/NotaCreditoSolicitudGolem" }, "facturaExterna": { "$ref": "#/components/examples/NotaCreditoSolicitudExterna" } } } } }, "responses": { "201": { "$ref": "#/components/responses/ComprobanteCreado" }, "202": { "$ref": "#/components/responses/ComprobanteEnProceso" }, "400": { "$ref": "#/components/responses/SolicitudInvalida" }, "401": { "$ref": "#/components/responses/NoAutenticado" }, "402": { "$ref": "#/components/responses/SinCreditos" }, "403": { "$ref": "#/components/responses/Prohibido" }, "409": { "$ref": "#/components/responses/ConflictoIdempotencia" }, "413": { "$ref": "#/components/responses/CuerpoDemasiadoGrande" }, "415": { "$ref": "#/components/responses/TipoContenidoNoSoportado" }, "422": { "$ref": "#/components/responses/ReglaNoCumplida" }, "429": { "$ref": "#/components/responses/LimiteExcedido" }, "500": { "$ref": "#/components/responses/ErrorInterno" }, "503": { "$ref": "#/components/responses/NoDisponible" } } } }, "/comprobantes/retenciones": { "post": { "tags": [ "Emisión" ], "operationId": "emitirRetencion", "summary": "Emitir un comprobante de retención", "description": "Crea un comprobante de retención (código 07, esquema 1.0.0 del SRI) sobre un documento sustento recibido de\nun proveedor.\n\n- Cada línea de `retenciones` indica el impuesto (`codigoImpuesto`: 1 renta, 2 IVA), el código de retención\n del catálogo y la base imponible. Golem calcula el valor retenido.\n- El porcentaje sale del catálogo. Solo los códigos de porcentaje variable (`porcentajeVariable: true` en\n el catálogo) requieren `porcentaje`.\n- El sujeto retenido debe estar identificado con RUC, cédula, pasaporte o identificación del exterior: no\n se admite consumidor final.\n- El período fiscal es el mes y año de la fecha de emisión de la retención.\n- La retención se emite dentro de los 5 días siguientes a la recepción del documento sustento. Golem no\n conoce esa fecha de recepción: el plazo es responsabilidad de tu empresa.\n", "externalDocs": { "url": "https://golem.ec/desarrolladores/retenciones/" }, "x-limites": [ "general", "emision" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/Prefer" }, { "$ref": "#/components/parameters/XRequestIdEntrada" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetencionSolicitud" }, "examples": { "rentaEIva": { "$ref": "#/components/examples/RetencionSolicitud" } } } } }, "responses": { "201": { "$ref": "#/components/responses/ComprobanteCreado" }, "202": { "$ref": "#/components/responses/ComprobanteEnProceso" }, "400": { "$ref": "#/components/responses/SolicitudInvalida" }, "401": { "$ref": "#/components/responses/NoAutenticado" }, "402": { "$ref": "#/components/responses/SinCreditos" }, "403": { "$ref": "#/components/responses/Prohibido" }, "409": { "$ref": "#/components/responses/ConflictoIdempotencia" }, "413": { "$ref": "#/components/responses/CuerpoDemasiadoGrande" }, "415": { "$ref": "#/components/responses/TipoContenidoNoSoportado" }, "422": { "$ref": "#/components/responses/ReglaNoCumplida" }, "429": { "$ref": "#/components/responses/LimiteExcedido" }, "500": { "$ref": "#/components/responses/ErrorInterno" }, "503": { "$ref": "#/components/responses/NoDisponible" } } } }, "/comprobantes": { "get": { "tags": [ "Consulta" ], "operationId": "listarComprobantes", "summary": "Listar comprobantes", "description": "Lista los comprobantes de la empresa del token en su ambiente. Incluye los emitidos desde la aplicación y\ndesde el API.\n\n- Sin `cambiadoDesde`: filtra por fecha de emisión (`desde`/`hasta`, rango de hasta 366 días) y ordena del\n más reciente al más antiguo.\n- Con `cambiadoDesde`: devuelve los comprobantes creados o modificados (estado, anulación u otro dato)\n desde ese instante, ordenados por `fechaActualizacion` del más antiguo al más reciente. `desde` y\n `hasta` son opcionales y no tienen valor por defecto. Guarda el `fechaActualizacion` del último\n comprobante que procesaste y úsalo como `cambiadoDesde` en la siguiente consulta: es la forma\n recomendada de seguir los cambios de estado, en lugar de consultar cada clave de acceso.\n", "externalDocs": { "url": "https://golem.ec/desarrolladores/listado/" }, "x-limites": [ "general" ], "parameters": [ { "$ref": "#/components/parameters/XRequestIdEntrada" }, { "name": "tipo", "in": "query", "description": "Tipo de comprobante.", "schema": { "$ref": "#/components/schemas/TipoComprobante" } }, { "name": "estado", "in": "query", "description": "Estado del comprobante.", "schema": { "$ref": "#/components/schemas/EstadoComprobante" } }, { "name": "cambiadoDesde", "in": "query", "description": "Instante ISO 8601 (con zona). Devuelve los comprobantes con `fechaActualizacion` igual o posterior, del\nmás antiguo al más reciente. No puede ser anterior a 90 días.\n", "schema": { "type": "string", "format": "date-time" }, "example": "2026-09-26T09:15:04.120-05:00" }, { "name": "desde", "in": "query", "description": "Fecha de emisión inicial, incluida. Sin `cambiadoDesde`, por defecto 30 días antes de `hasta`.", "schema": { "type": "string", "format": "date" }, "example": "2026-09-01" }, { "name": "hasta", "in": "query", "description": "Fecha de emisión final, incluida. Sin `cambiadoDesde`, por defecto hoy.", "schema": { "type": "string", "format": "date" }, "example": "2026-09-30" }, { "name": "establecimiento", "in": "query", "description": "Código del establecimiento.", "schema": { "type": "string", "pattern": "^\\d{3}$" }, "example": "001" }, { "name": "puntoEmision", "in": "query", "description": "Código del punto de emisión. Requiere `establecimiento`.", "schema": { "type": "string", "pattern": "^\\d{3}$" }, "example": "001" }, { "name": "identificacion", "in": "query", "description": "Identificación del cliente o del sujeto retenido.", "schema": { "type": "string", "minLength": 3, "maxLength": 20 }, "example": "0990000000001" }, { "name": "numero", "in": "query", "description": "Número completo del comprobante.", "schema": { "type": "string", "pattern": "^\\d{3}-\\d{3}-\\d{9}$" }, "example": "001-001-000000148" }, { "name": "referencia", "in": "query", "description": "Referencia que envió el integrador al emitir.", "schema": { "type": "string", "maxLength": 100 }, "example": "PED-2026-00481" }, { "name": "origen", "in": "query", "description": "Canal por el que se creó el comprobante.", "schema": { "$ref": "#/components/schemas/Origen" } }, { "name": "pagina", "in": "query", "description": "Número de página, desde 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "porPagina", "in": "query", "description": "Comprobantes por página.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Página de comprobantes.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListaComprobantes" }, "examples": { "pagina": { "$ref": "#/components/examples/ListaComprobantes" } } } } }, "400": { "$ref": "#/components/responses/SolicitudInvalida" }, "401": { "$ref": "#/components/responses/NoAutenticado" }, "429": { "$ref": "#/components/responses/LimiteExcedido" }, "500": { "$ref": "#/components/responses/ErrorInterno" } } } }, "/comprobantes/{claveAcceso}": { "get": { "tags": [ "Consulta" ], "operationId": "consultarComprobante", "summary": "Consultar un comprobante", "description": "Devuelve el comprobante con su estado, número de autorización, totales, ítems y los mensajes del SRI.\nSirve para cualquier comprobante de la empresa del token en su ambiente, emitido desde la aplicación o desde\nel API. Un comprobante de otra empresa o de otro ambiente responde `404`.\n", "externalDocs": { "url": "https://golem.ec/desarrolladores/consulta-y-descargas/" }, "x-limites": [ "general" ], "parameters": [ { "$ref": "#/components/parameters/ClaveAcceso" }, { "$ref": "#/components/parameters/XRequestIdEntrada" } ], "responses": { "200": { "description": "El comprobante.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comprobante" }, "examples": { "facturaAutorizada": { "$ref": "#/components/examples/FacturaAutorizada" }, "facturaDevuelta": { "$ref": "#/components/examples/FacturaDevuelta" }, "notaCredito": { "$ref": "#/components/examples/NotaCreditoAutorizada" }, "retencion": { "$ref": "#/components/examples/RetencionAutorizada" } } } } }, "400": { "$ref": "#/components/responses/SolicitudInvalida" }, "401": { "$ref": "#/components/responses/NoAutenticado" }, "404": { "$ref": "#/components/responses/NoEncontrado" }, "429": { "$ref": "#/components/responses/LimiteExcedido" }, "500": { "$ref": "#/components/responses/ErrorInterno" } } } }, "/comprobantes/{claveAcceso}/pdf": { "get": { "tags": [ "Consulta" ], "operationId": "descargarPdf", "summary": "Descargar el RIDE en PDF", "description": "Devuelve el RIDE (representación impresa) del comprobante autorizado. Un comprobante que no llegó a\nautorizarse no tiene RIDE válido y responde `409 ESTADO_NO_PERMITE`. Un comprobante anulado en Golem que\nestuvo autorizado sí se puede descargar.\n", "externalDocs": { "url": "https://golem.ec/desarrolladores/consulta-y-descargas/" }, "x-limites": [ "general" ], "parameters": [ { "$ref": "#/components/parameters/ClaveAcceso" }, { "$ref": "#/components/parameters/XRequestIdEntrada" } ], "responses": { "200": { "description": "El archivo PDF.", "headers": { "Content-Disposition": { "$ref": "#/components/headers/ContentDispositionPdf" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/pdf": { "schema": { "type": "string", "contentMediaType": "application/pdf" } } } }, "400": { "$ref": "#/components/responses/SolicitudInvalida" }, "401": { "$ref": "#/components/responses/NoAutenticado" }, "404": { "$ref": "#/components/responses/NoEncontrado" }, "409": { "$ref": "#/components/responses/EstadoNoPermite" }, "429": { "$ref": "#/components/responses/LimiteExcedido" }, "500": { "$ref": "#/components/responses/ErrorInterno" }, "503": { "$ref": "#/components/responses/NoDisponible" } } } }, "/comprobantes/{claveAcceso}/xml": { "get": { "tags": [ "Consulta" ], "operationId": "descargarXml", "summary": "Descargar el XML autorizado", "description": "Devuelve el XML autorizado con el envoltorio de autorización del SRI: el elemento `autorizacion` con\n`estado`, `numeroAutorizacion`, `fechaAutorizacion`, `ambiente` y el comprobante firmado dentro de\n`comprobante` (CDATA). Es el archivo que se entrega al receptor y que se conserva por 7 años.\n\nSolo existe para comprobantes autorizados (también los anulados en Golem que estuvieron autorizados). Si el\nXML no está en el almacenamiento de Golem, se pide al SRI; si el SRI no responde, `503` con `Retry-After`.\n", "externalDocs": { "url": "https://golem.ec/desarrolladores/consulta-y-descargas/" }, "x-limites": [ "general" ], "parameters": [ { "$ref": "#/components/parameters/ClaveAcceso" }, { "$ref": "#/components/parameters/XRequestIdEntrada" } ], "responses": { "200": { "description": "El XML autorizado.", "headers": { "Content-Disposition": { "$ref": "#/components/headers/ContentDispositionXml" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/xml": { "schema": { "type": "string" }, "examples": { "autorizado": { "$ref": "#/components/examples/XmlAutorizado" } } } } }, "400": { "$ref": "#/components/responses/SolicitudInvalida" }, "401": { "$ref": "#/components/responses/NoAutenticado" }, "404": { "$ref": "#/components/responses/NoEncontrado" }, "409": { "$ref": "#/components/responses/EstadoNoPermite" }, "429": { "$ref": "#/components/responses/LimiteExcedido" }, "500": { "$ref": "#/components/responses/ErrorInterno" }, "503": { "$ref": "#/components/responses/NoDisponible" } } } }, "/comprobantes/{claveAcceso}/reprocesar": { "post": { "tags": [ "Acciones" ], "operationId": "reprocesarComprobante", "summary": "Reprocesar un comprobante", "description": "Vuelve a procesar un comprobante que no terminó bien, con la misma clave de acceso y el mismo número:\n\n| Estado | Qué hace |\n|---|---|\n| `EN_PROCESO`, aún sin enviar | Lo firma y lo envía al SRI. |\n| `EN_PROCESO`, ya recibido por el SRI | Consulta la autorización. |\n| `DEVUELTO` o `ERROR` | Lo firma y lo envía otra vez. Consume un crédito de nuevo antes de enviarlo: sin créditos responde `402` y el comprobante no cambia. Si el SRI lo vuelve a rechazar, el crédito regresa. |\n| `AUTORIZADO`, `NO_AUTORIZADO` o `ANULADO` | No se puede: responde `409`. Para corregir un comprobante no autorizado, emite uno nuevo. |\n\nUn comprobante devuelto por un error en sus datos se vuelve a devolver: en ese caso emite uno nuevo. Usa el\nreproceso cuando la causa ya se corrigió fuera del comprobante (por ejemplo, la firma electrónica) o fue\ntemporal. El comprobante conserva su fecha de emisión: si ya pasó más de un día, el SRI puede devolverlo por\nfecha extemporánea. Espera el resultado igual que la emisión y acepta la misma cabecera `Prefer`.\n\nReprocesar firma y envía el comprobante con el número de su punto de emisión, igual que emitir: un token\nrestringido a algunos puntos solo reprocesa los comprobantes de esos puntos, y uno sin puntos permitidos no\nreprocesa ninguno. En esos casos responde `403 PUNTO_NO_PERMITIDO`.\n", "externalDocs": { "url": "https://golem.ec/desarrolladores/estados/" }, "x-limites": [ "general", "emision" ], "parameters": [ { "$ref": "#/components/parameters/ClaveAcceso" }, { "$ref": "#/components/parameters/Prefer" }, { "$ref": "#/components/parameters/XRequestIdEntrada" } ], "responses": { "200": { "description": "El comprobante llegó a un estado final.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comprobante" }, "examples": { "autorizada": { "$ref": "#/components/examples/FacturaAutorizada" } } } } }, "202": { "$ref": "#/components/responses/ComprobanteEnProceso" }, "400": { "$ref": "#/components/responses/SolicitudInvalida" }, "401": { "$ref": "#/components/responses/NoAutenticado" }, "402": { "$ref": "#/components/responses/SinCreditos" }, "403": { "$ref": "#/components/responses/Prohibido" }, "404": { "$ref": "#/components/responses/NoEncontrado" }, "409": { "$ref": "#/components/responses/EstadoNoPermite" }, "429": { "$ref": "#/components/responses/LimiteExcedido" }, "500": { "$ref": "#/components/responses/ErrorInterno" } } } }, "/comprobantes/{claveAcceso}/correo": { "post": { "tags": [ "Acciones" ], "operationId": "reenviarCorreo", "summary": "Reenviar el correo del comprobante", "description": "Vuelve a enviar el correo con el XML y el RIDE al email que se usó al emitir el comprobante. Solo para\ncomprobantes autorizados. En el ambiente de pruebas el correo va a un buzón de Golem, nunca al receptor.\nEl envío se hace en segundo plano: la respuesta `202` confirma que quedó en cola.\n\nEl reenvío no cambia el comprobante ni consume créditos, así que no depende de los puntos de emisión del\ntoken: cualquier token de la empresa puede reenviar el correo de sus comprobantes.\n", "externalDocs": { "url": "https://golem.ec/desarrolladores/estados/" }, "x-limites": [ "general", "correo" ], "parameters": [ { "$ref": "#/components/parameters/ClaveAcceso" }, { "$ref": "#/components/parameters/XRequestIdEntrada" } ], "responses": { "202": { "description": "El correo quedó en cola de envío.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvioCorreo" }, "examples": { "enCola": { "value": { "claveAcceso": "2409202601179000000000120010010000001481234567815", "destinatario": "fa******@cliente-demo.ec", "mensaje": "El correo se envía en segundo plano." } } } } } }, "400": { "$ref": "#/components/responses/SolicitudInvalida" }, "401": { "$ref": "#/components/responses/NoAutenticado" }, "403": { "$ref": "#/components/responses/Prohibido" }, "404": { "$ref": "#/components/responses/NoEncontrado" }, "409": { "$ref": "#/components/responses/EstadoNoPermite" }, "422": { "$ref": "#/components/responses/ReglaNoCumplida" }, "429": { "$ref": "#/components/responses/LimiteExcedido" }, "500": { "$ref": "#/components/responses/ErrorInterno" } } } }, "/empresa": { "get": { "tags": [ "Empresa" ], "operationId": "consultarEmpresa", "summary": "Consultar la empresa del token", "description": "Devuelve el RUC y los datos tributarios de la empresa, sus establecimientos y puntos de emisión con los\nsiguientes secuenciales del ambiente del token, los créditos disponibles, la vigencia de la firma\nelectrónica (nunca el certificado ni su clave) y los datos del token que se usó: su punto de emisión por\ndefecto y los puntos en los que puede emitir.\n", "externalDocs": { "url": "https://golem.ec/desarrolladores/empresa/" }, "x-limites": [ "general" ], "parameters": [ { "$ref": "#/components/parameters/XRequestIdEntrada" } ], "responses": { "200": { "description": "La empresa del token.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empresa" }, "examples": { "empresa": { "$ref": "#/components/examples/Empresa" } } } } }, "401": { "$ref": "#/components/responses/NoAutenticado" }, "429": { "$ref": "#/components/responses/LimiteExcedido" }, "500": { "$ref": "#/components/responses/ErrorInterno" } } } }, "/ruc/{ruc}": { "get": { "tags": [ "RUC" ], "operationId": "consultarRuc", "summary": "Consultar un RUC en el catastro del SRI", "description": "Consulta en el catastro público del SRI la razón social, el estado, el régimen y los establecimientos de un\nRUC. Sirve para completar los datos de un cliente o de un proveedor antes de emitir. Depende de la\ndisponibilidad del SRI: si no responde, `503` con `Retry-After`. Las respuestas se guardan en caché hasta\nuna hora.\n", "externalDocs": { "url": "https://golem.ec/desarrolladores/ruc/" }, "x-limites": [ "general", "ruc" ], "parameters": [ { "name": "ruc", "in": "path", "required": true, "description": "RUC de 13 dígitos terminado en 001.", "schema": { "type": "string", "pattern": "^\\d{10}001$" }, "example": "1760013210001" }, { "$ref": "#/components/parameters/XRequestIdEntrada" } ], "responses": { "200": { "description": "Datos del RUC según el SRI.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ruc" }, "examples": { "entidadPublica": { "$ref": "#/components/examples/Ruc" } } } } }, "400": { "$ref": "#/components/responses/SolicitudInvalida" }, "401": { "$ref": "#/components/responses/NoAutenticado" }, "404": { "description": "El SRI no registra ese RUC.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "noRegistrado": { "value": { "error": { "codigo": "RUC_NO_REGISTRADO", "mensaje": "El SRI no registra este RUC.", "campo": "ruc", "detalles": [], "requestId": "5f0c8e2a-7c1b-4f7e-9a51-3c2d9b8e6a10" } } } } } } }, "429": { "$ref": "#/components/responses/LimiteExcedido" }, "500": { "$ref": "#/components/responses/ErrorInterno" }, "503": { "$ref": "#/components/responses/NoDisponible" } } } }, "/catalogos": { "get": { "tags": [ "Catálogos" ], "operationId": "listarCatalogos", "summary": "Listar los catálogos", "description": "Nombres y descripción de los catálogos del SRI disponibles. No requiere token.", "security": [], "externalDocs": { "url": "https://golem.ec/desarrolladores/catalogos/" }, "x-limites": [ "publico" ], "responses": { "200": { "description": "Catálogos disponibles.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Cache-Control": { "$ref": "#/components/headers/CacheControlPublico" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "datos" ], "properties": { "datos": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogoResumen" } } } }, "examples": { "lista": { "value": { "datos": [ { "nombre": "tipos-identificacion", "descripcion": "Tipos de identificación del comprador o del sujeto retenido.", "fuente": "Ficha técnica de comprobantes electrónicos del SRI, tabla 6." }, { "nombre": "formas-pago", "descripcion": "Formas de pago de una factura.", "fuente": "Ficha técnica de comprobantes electrónicos del SRI, tabla 24." }, { "nombre": "tarifas-iva", "descripcion": "Códigos de porcentaje de IVA y su vigencia.", "fuente": "Ficha técnica de comprobantes electrónicos del SRI, tabla 17." }, { "nombre": "retenciones-renta", "descripcion": "Códigos de retención en la fuente del impuesto a la renta.", "fuente": "Catálogo de retenciones del SRI (anexo transaccional simplificado)." }, { "nombre": "retenciones-iva", "descripcion": "Códigos de retención del IVA.", "fuente": "Ficha técnica de comprobantes electrónicos del SRI, tabla 21." }, { "nombre": "tipos-documento-sustento", "descripcion": "Tipos de comprobante que sustentan una retención, incluida la liquidación de compra emitida fuera de Golem.", "fuente": "Tipos de comprobantes autorizados por el SRI." } ] } } } } } }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } } }, "/catalogos/{nombre}": { "get": { "tags": [ "Catálogos" ], "operationId": "consultarCatalogo", "summary": "Consultar un catálogo", "description": "Códigos que acepta el API, con su nombre y, según el catálogo, su porcentaje y su fecha de vigencia. Solo se\nlistan los códigos vigentes, salvo en `tarifas-iva`, que incluye las tarifas anteriores porque las notas de\ncrédito las usan. No requiere token.\n", "security": [], "externalDocs": { "url": "https://golem.ec/desarrolladores/catalogos/" }, "x-limites": [ "publico" ], "parameters": [ { "name": "nombre", "in": "path", "required": true, "description": "Nombre del catálogo.", "schema": { "$ref": "#/components/schemas/NombreCatalogo" } } ], "responses": { "200": { "description": "El catálogo.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Cache-Control": { "$ref": "#/components/headers/CacheControlPublico" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Catalogo" }, "examples": { "formasPago": { "$ref": "#/components/examples/CatalogoFormasPago" }, "tarifasIva": { "$ref": "#/components/examples/CatalogoTarifasIva" }, "retencionesRenta": { "$ref": "#/components/examples/CatalogoRetencionesRenta" } } } } }, "404": { "$ref": "#/components/responses/CatalogoNoEncontrado" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } } }, "/openapi.json": { "get": { "tags": [ "Especificación" ], "operationId": "obtenerEspecificacion", "summary": "Obtener esta especificación OpenAPI", "description": "La especificación OpenAPI 3.1 del API en JSON. No requiere token.", "security": [], "x-limites": [ "publico" ], "responses": { "200": { "description": "Especificación OpenAPI.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlPublico" } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "glm_prod_… o glm_prueba_… (prefijo del ambiente y 40 caracteres)", "description": "Token de la empresa creado en Cuenta > API e integraciones. `glm_prod_` emite en producción y `glm_prueba_`\nen el ambiente de pruebas del SRI.\n" } }, "parameters": { "ClaveAcceso": { "name": "claveAcceso", "in": "path", "required": true, "description": "Clave de acceso de 49 dígitos del comprobante.", "schema": { "type": "string", "pattern": "^\\d{49}$" }, "example": "2409202601179000000000120010010000001481234567815" }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Clave única de la operación, generada por tu sistema (se recomienda un UUID v4). Entre 8 y 100 caracteres:\nletras, números, `-`, `_`, `.` o `:`. Vale 24 horas por empresa y por ambiente. Es opcional, pero sin ella\nun reintento después de un corte de red crea otro comprobante.\n", "schema": { "type": "string", "minLength": 8, "maxLength": 100, "pattern": "^[A-Za-z0-9._:-]{8,100}$" }, "example": "3f6c2a8e-1b4d-4c52-9a0e-7d1f2b3c4d5e" }, "Prefer": { "name": "Prefer", "in": "header", "required": false, "description": "`respond-async` responde de inmediato con `202` sin esperar al SRI. Sin esta cabecera, Golem espera el\nresultado hasta 12 segundos. Otros valores se ignoran.\n", "schema": { "type": "string" }, "examples": { "asincrono": { "value": "respond-async" } } }, "XRequestIdEntrada": { "name": "X-Request-Id", "in": "header", "required": false, "description": "Identificador propio de la solicitud (hasta 64 caracteres: letras, números y `-`). Si no lo envías, Golem\ngenera uno. Vuelve en la cabecera de respuesta y en los errores; cítalo al escribir a soporte.\n", "schema": { "type": "string", "maxLength": 64, "pattern": "^[A-Za-z0-9-]{1,64}$" } } }, "headers": { "XRequestId": { "description": "Identificador de la solicitud. Cítalo al escribir a soporte.", "schema": { "type": "string" }, "example": "5f0c8e2a-7c1b-4f7e-9a51-3c2d9b8e6a10" }, "RateLimitLimit": { "description": "Solicitudes permitidas en la ventana del límite que aplica a esta solicitud y que está más cerca de agotarse.", "schema": { "type": "integer" }, "example": 60 }, "RateLimitRemaining": { "description": "Solicitudes que quedan en la ventana actual de ese límite.", "schema": { "type": "integer" }, "example": 57 }, "RateLimitReset": { "description": "Segundos hasta que la ventana de ese límite se reinicia.", "schema": { "type": "integer" }, "example": 42 }, "RetryAfter": { "description": "Segundos que conviene esperar antes de reintentar.", "schema": { "type": "integer" }, "example": 42 }, "Location": { "description": "URL del comprobante creado.", "schema": { "type": "string", "format": "uri" }, "example": "https://api.golem.ec/v1/comprobantes/2409202601179000000000120010010000001481234567815" }, "IdempotentReplayed": { "description": "`true` cuando la respuesta corresponde a una solicitud anterior con la misma Idempotency-Key.", "schema": { "type": "string", "enum": [ "true" ] } }, "PreferenceApplied": { "description": "Preferencia de `Prefer` que se aplicó.", "schema": { "type": "string" }, "example": "respond-async" }, "ContentDispositionPdf": { "description": "Nombre del archivo, formado por el tipo y el número del comprobante.", "schema": { "type": "string" }, "example": "attachment; filename=\"factura-001-001-000000148.pdf\"" }, "ContentDispositionXml": { "description": "Nombre del archivo, formado por el tipo y el número del comprobante.", "schema": { "type": "string" }, "example": "attachment; filename=\"factura-001-001-000000148.xml\"" }, "CacheControlPublico": { "description": "Las respuestas públicas se pueden guardar en caché una hora.", "schema": { "type": "string" }, "example": "public, max-age=3600" } }, "responses": { "ComprobanteCreado": { "description": "Comprobante creado y procesado hasta un estado final: `AUTORIZADO`, `NO_AUTORIZADO`, `DEVUELTO` o `ERROR`.\nEn los tres últimos el crédito vuelve al saldo y los motivos están en `mensajes`.\n", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comprobante" }, "examples": { "facturaAutorizada": { "$ref": "#/components/examples/FacturaAutorizada" }, "facturaDevuelta": { "$ref": "#/components/examples/FacturaDevuelta" }, "notaCredito": { "$ref": "#/components/examples/NotaCreditoAutorizada" }, "retencion": { "$ref": "#/components/examples/RetencionAutorizada" } } } } }, "ComprobanteEnProceso": { "description": "Comprobante creado; el SRI aún no responde. Estado `EN_PROCESO`. Consulta `Location` más tarde (por ejemplo\na los 5, 15 y 60 segundos). Golem reintenta el envío y la autorización por su cuenta.\n", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Preference-Applied": { "$ref": "#/components/headers/PreferenceApplied" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comprobante" }, "examples": { "enProceso": { "$ref": "#/components/examples/FacturaEnProceso" } } } } }, "SolicitudInvalida": { "description": "La solicitud no se puede leer o tiene datos inválidos (`JSON_INVALIDO`, `VALIDACION`,\n`PARAMETRO_INVALIDO`, `IDEMPOTENCY_KEY_INVALIDA`, `TOKEN_EN_URL`). En `VALIDACION`, `detalles` lista cada\ncampo con error.\n", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "validacion": { "$ref": "#/components/examples/ErrorValidacion" }, "json": { "value": { "error": { "codigo": "JSON_INVALIDO", "mensaje": "El cuerpo no es un JSON válido: falta una coma o una llave cerca de la línea 7.", "campo": null, "detalles": [], "requestId": "5f0c8e2a-7c1b-4f7e-9a51-3c2d9b8e6a10" } } } } } } }, "NoAutenticado": { "description": "Falta el token, no es válido o fue revocado (`TOKEN_REQUERIDO`, `TOKEN_INVALIDO`, `TOKEN_REVOCADO`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "WWW-Authenticate": { "description": "Esquema de autenticación.", "schema": { "type": "string" }, "example": "Bearer realm=\"golem\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "sinToken": { "value": { "error": { "codigo": "TOKEN_REQUERIDO", "mensaje": "Envía el token en la cabecera Authorization: Bearer .", "campo": null, "detalles": [], "requestId": "5f0c8e2a-7c1b-4f7e-9a51-3c2d9b8e6a10" } } }, "revocado": { "value": { "error": { "codigo": "TOKEN_REVOCADO", "mensaje": "Este token fue revocado. Crea otro en Cuenta > API e integraciones.", "campo": null, "detalles": [], "requestId": "5f0c8e2a-7c1b-4f7e-9a51-3c2d9b8e6a10" } } } } } } }, "SinCreditos": { "description": "La empresa no tiene créditos disponibles (`SIN_CREDITOS`). No se creó el comprobante.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "sinCreditos": { "value": { "error": { "codigo": "SIN_CREDITOS", "mensaje": "Tu empresa no tiene créditos disponibles. Recarga en golem.ec para seguir emitiendo.", "campo": null, "detalles": [], "requestId": "5f0c8e2a-7c1b-4f7e-9a51-3c2d9b8e6a10" } } } } } } }, "Prohibido": { "description": "El token no puede hacer esta operación (`EMPRESA_SUSPENDIDA`, `PUNTO_NO_PERMITIDO`, `PLAN_NO_PERMITE`). Con\nla empresa suspendida, las consultas y descargas siguen disponibles.\n", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "puntoNoPermitido": { "value": { "error": { "codigo": "PUNTO_NO_PERMITIDO", "mensaje": "Este token solo puede emitir en el punto 001-002.", "campo": "puntoEmision", "detalles": [], "requestId": "5f0c8e2a-7c1b-4f7e-9a51-3c2d9b8e6a10" } } } } } } }, "CatalogoNoEncontrado": { "description": "No existe un catálogo con ese nombre (`NO_ENCONTRADO`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "noExiste": { "value": { "error": { "codigo": "NO_ENCONTRADO", "mensaje": "No existe el catálogo \"monedas\". Consulta la lista en GET /catalogos.", "campo": "nombre", "detalles": [], "requestId": "5f0c8e2a-7c1b-4f7e-9a51-3c2d9b8e6a10" } } } } } } }, "NoEncontrado": { "description": "No existe el recurso en la empresa y el ambiente del token (`NO_ENCONTRADO`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "noEncontrado": { "value": { "error": { "codigo": "NO_ENCONTRADO", "mensaje": "No encontramos un comprobante con esa clave de acceso en tu empresa y en este ambiente.", "campo": "claveAcceso", "detalles": [], "requestId": "5f0c8e2a-7c1b-4f7e-9a51-3c2d9b8e6a10" } } } } } } }, "ConflictoIdempotencia": { "description": "La `Idempotency-Key` ya se usó con otro cuerpo o en otra ruta (`IDEMPOTENCIA_CUERPO_DISTINTO`), o la\nsolicitud original todavía se está procesando (`IDEMPOTENCIA_EN_PROCESO`, con `Retry-After`).\n", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "cuerpoDistinto": { "value": { "error": { "codigo": "IDEMPOTENCIA_CUERPO_DISTINTO", "mensaje": "Esta Idempotency-Key ya se usó con otro cuerpo. Usa una clave nueva para otra operación.", "campo": "Idempotency-Key", "detalles": [], "requestId": "5f0c8e2a-7c1b-4f7e-9a51-3c2d9b8e6a10" } } }, "enProceso": { "value": { "error": { "codigo": "IDEMPOTENCIA_EN_PROCESO", "mensaje": "La solicitud original con esta Idempotency-Key todavía se está procesando. Reintenta en unos segundos.", "campo": "Idempotency-Key", "detalles": [], "requestId": "5f0c8e2a-7c1b-4f7e-9a51-3c2d9b8e6a10" } } } } } } }, "EstadoNoPermite": { "description": "El estado del comprobante no permite esta operación (`ESTADO_NO_PERMITE`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "noAutorizado": { "value": { "error": { "codigo": "ESTADO_NO_PERMITE", "mensaje": "El comprobante está DEVUELTO; el RIDE y el XML autorizado solo existen para comprobantes autorizados.", "campo": null, "detalles": [], "requestId": "5f0c8e2a-7c1b-4f7e-9a51-3c2d9b8e6a10" } } } } } } }, "CuerpoDemasiadoGrande": { "description": "El cuerpo supera 256 KB (`CUERPO_DEMASIADO_GRANDE`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "TipoContenidoNoSoportado": { "description": "El cuerpo de una emisión debe ir como `Content-Type: application/json` (`TIPO_CONTENIDO_NO_SOPORTADO`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ReglaNoCumplida": { "description": "Los datos son válidos en forma pero no cumplen una regla del SRI o de la empresa. No se creó el comprobante\nni se consumió crédito. Códigos: `PUNTO_EMISION_NO_EXISTE`, `IDENTIFICACION_INVALIDA`,\n`TARIFA_IVA_NO_VIGENTE`, `TARIFA_IVA_NO_COINCIDE`, `PAGOS_NO_CUADRAN`,\n`TOTAL_NO_COINCIDE`, `DESCUENTO_INVALIDO`, `CONSUMIDOR_FINAL_EXCEDE_LIMITE`, `FECHA_FUERA_DE_RANGO`,\n`FIRMA_NO_VIGENTE`, `SIN_STOCK`, `SUSTENTO_NO_ENCONTRADO`, `SUSTENTO_NO_AUTORIZADO`,\n`NOTA_CREDITO_EXCEDE_SALDO`, `CLIENTE_NO_COINCIDE`, `CLIENTE_NO_PERMITIDO`, `CODIGO_RETENCION_INVALIDO`,\n`PORCENTAJE_RETENCION_INVALIDO`, `SIN_CORREO`.\n", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "totalNoCoincide": { "$ref": "#/components/examples/ErrorTotalNoCoincide" }, "firma": { "value": { "error": { "codigo": "FIRMA_NO_VIGENTE", "mensaje": "La firma electrónica de tu empresa venció el 2026-09-20. Carga una vigente en Cuenta > Firma electrónica.", "campo": null, "detalles": [], "requestId": "5f0c8e2a-7c1b-4f7e-9a51-3c2d9b8e6a10" } } }, "fecha": { "value": { "error": { "codigo": "FECHA_FUERA_DE_RANGO", "mensaje": "La fecha de emisión debe ser la de hoy (2026-09-26, hora de Ecuador) o la de ayer. El SRI exige transmitir el comprobante al emitirlo.", "campo": "fechaEmision", "detalles": [], "requestId": "5f0c8e2a-7c1b-4f7e-9a51-3c2d9b8e6a10" } } }, "consumidorFinal": { "value": { "error": { "codigo": "CONSUMIDOR_FINAL_EXCEDE_LIMITE", "mensaje": "Una factura a consumidor final no puede superar USD 50.00. Identifica al comprador.", "campo": "cliente.identificacion", "detalles": [], "requestId": "5f0c8e2a-7c1b-4f7e-9a51-3c2d9b8e6a10" } } } } } } }, "LimiteExcedido": { "description": "Se superó un límite de solicitudes (`LIMITE_EXCEDIDO`). Reintenta después de `Retry-After` segundos.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "emision": { "value": { "error": { "codigo": "LIMITE_EXCEDIDO", "mensaje": "Superaste el límite de 20 emisiones por minuto de este token. Reintenta en 18 segundos.", "campo": null, "detalles": [], "requestId": "5f0c8e2a-7c1b-4f7e-9a51-3c2d9b8e6a10" } } } } } } }, "ErrorInterno": { "description": "Error inesperado de Golem (`ERROR_INTERNO`). Si ocurrió al emitir, consulta el listado antes de reintentar sin Idempotency-Key.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NoDisponible": { "description": "Un servicio del que depende la operación no responde (`SRI_NO_DISPONIBLE`, `SERVICIO_NO_DISPONIBLE`,\n`MANTENIMIENTO`). Reintenta después de `Retry-After` segundos.\n", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "sri": { "value": { "error": { "codigo": "SRI_NO_DISPONIBLE", "mensaje": "El SRI no responde en este momento. Reintenta en unos minutos.", "campo": null, "detalles": [], "requestId": "5f0c8e2a-7c1b-4f7e-9a51-3c2d9b8e6a10" } } } } } } } }, "schemas": { "Ambiente": { "type": "string", "description": "Ambiente del SRI. Lo decide el token.", "enum": [ "PRUEBAS", "PRODUCCION" ] }, "TipoComprobante": { "type": "string", "description": "Tipo de comprobante: FACTURA (01), NOTA_CREDITO (04), RETENCION (07).", "enum": [ "FACTURA", "NOTA_CREDITO", "RETENCION" ] }, "CodigoDocumento": { "type": "string", "description": "Código del tipo de comprobante en el SRI (tabla 3): 01 factura, 04 nota de crédito, 07 retención.", "enum": [ "01", "04", "07" ] }, "EstadoComprobante": { "type": "string", "description": "- `EN_PROCESO`: guardado; aún no se envía al SRI o el SRI no responde la autorización.\n- `AUTORIZADO`: el SRI lo autorizó.\n- `NO_AUTORIZADO`: el SRI no lo autorizó (decisión final para esa clave de acceso).\n- `DEVUELTO`: el SRI no lo recibió por un error en los datos (en la aplicación aparece como Rechazado).\n- `ERROR`: Golem no pudo firmarlo o enviarlo.\n- `ANULADO`: anulado en Golem; ver `anulacion.estadoSri`.\n", "enum": [ "EN_PROCESO", "AUTORIZADO", "NO_AUTORIZADO", "DEVUELTO", "ERROR", "ANULADO" ] }, "Origen": { "type": "string", "description": "Canal por el que se creó el comprobante: `API` (este API), `API_ANTERIOR` (la ruta de integración anterior\na la versión 1) o `APP` (la aplicación web).\n", "enum": [ "API", "API_ANTERIOR", "APP" ] }, "CodigoTipoIdentificacion": { "type": "string", "description": "Tipo de identificación del SRI (tabla 6): 04 RUC, 05 cédula, 06 pasaporte, 07 consumidor final,\n08 identificación del exterior.\n", "enum": [ "04", "05", "06", "07", "08" ] }, "CodigoTipoIdentificacionSujeto": { "type": "string", "description": "Tipo de identificación del sujeto retenido: 04 RUC, 05 cédula, 06 pasaporte, 08 identificación del\nexterior. Una retención no se emite a consumidor final (07).\n", "enum": [ "04", "05", "06", "08" ] }, "CodigoFormaPago": { "type": "string", "description": "Forma de pago del SRI (tabla 24): 01 sin utilización del sistema financiero, 15 compensación de deudas,\n16 tarjeta de débito, 17 dinero electrónico, 18 tarjeta prepago, 19 tarjeta de crédito, 20 otros con\nutilización del sistema financiero, 21 endoso de títulos.\n", "enum": [ "01", "15", "16", "17", "18", "19", "20", "21" ] }, "CodigoIva": { "type": "string", "description": "Código de porcentaje de IVA del SRI (tabla 17): 0 (0 %), 2 (12 %, hasta el 31-03-2024), 3 (14 %, del\n01-06-2016 al 31-05-2017), 4 (15 %, desde el 01-04-2024), 5 (5 %), 6 (no objeto de IVA), 7 (exento de IVA),\n8 (IVA diferenciado), 10 (13 %).\n", "enum": [ "0", "2", "3", "4", "5", "6", "7", "8", "10" ] }, "UnidadTiempo": { "type": "string", "description": "Unidad del plazo de pago.", "enum": [ "DIAS", "MESES", "ANIOS" ] }, "TipoProducto": { "type": "string", "description": "Tipo del ítem. Solo se usa para crear el producto en el catálogo de la empresa cuando su código no existe.", "enum": [ "BIEN", "SERVICIO" ] }, "CodigoImpuestoRetencion": { "type": "string", "description": "Impuesto retenido: 1 renta, 2 IVA.", "enum": [ "1", "2" ] }, "NombreCatalogo": { "type": "string", "enum": [ "tipos-identificacion", "formas-pago", "tarifas-iva", "retenciones-renta", "retenciones-iva", "tipos-documento-sustento" ] }, "CodigoEstablecimiento": { "type": "string", "description": "Código de 3 dígitos del establecimiento, como en el número del comprobante.", "pattern": "^\\d{3}$", "examples": [ "001" ] }, "CodigoPuntoEmision": { "type": "string", "description": "Código de 3 dígitos del punto de emisión.", "pattern": "^\\d{3}$", "examples": [ "001" ] }, "NumeroComprobante": { "type": "string", "description": "Número del comprobante con establecimiento, punto de emisión y secuencial.", "pattern": "^\\d{3}-\\d{3}-\\d{9}$", "examples": [ "001-001-000000148" ] }, "ClaveAcceso": { "type": "string", "description": "Clave de acceso de 49 dígitos. En el esquema offline del SRI es también el número de autorización.", "pattern": "^\\d{49}$" }, "Instante": { "type": "string", "format": "date-time", "description": "Fecha y hora en ISO 8601 con la zona de Ecuador (-05:00).", "examples": [ "2026-09-24T10:42:31-05:00" ] }, "CampoAdicional": { "type": "object", "description": "Campo de información adicional del comprobante (se imprime en el RIDE y va en el XML).", "additionalProperties": false, "required": [ "nombre", "valor" ], "properties": { "nombre": { "type": "string", "minLength": 1, "maxLength": 300 }, "valor": { "type": "string", "minLength": 1, "maxLength": 300 } } }, "ClienteSolicitud": { "type": "object", "description": "Comprador. Sus datos se usan en este comprobante: la razón social, la dirección y el correo al que se envía.\nGolem no toma ni cambia los datos que otra empresa registró para la misma identificación. Si omites el\n`email`, se usa el último que tu empresa registró para ese cliente, si existe. Para consumidor final solo\nse usa el `email` de esta solicitud. En una nota de crédito no se admite consumidor final.\n", "additionalProperties": false, "required": [ "identificacion" ], "properties": { "tipoIdentificacion": { "$ref": "#/components/schemas/CodigoTipoIdentificacion" }, "identificacion": { "type": "string", "description": "Cédula (10 dígitos), RUC (13 dígitos), pasaporte o identificación del exterior. Para consumidor final,\n`9999999999999`. Si omites `tipoIdentificacion`, se deduce: 13 dígitos válidos → RUC, 10 dígitos\nválidos → cédula, `9999999999999` → consumidor final; en otro caso indícalo.\n", "minLength": 3, "maxLength": 20, "pattern": "^[A-Za-z0-9-]{3,20}$" }, "razonSocial": { "type": "string", "description": "Nombres y apellidos o razón social. Obligatorio salvo para consumidor final.", "minLength": 3, "maxLength": 300 }, "email": { "type": "string", "format": "email", "maxLength": 255 }, "direccion": { "type": "string", "maxLength": 300 }, "telefono": { "type": "string", "maxLength": 30 } } }, "SujetoRetenidoSolicitud": { "type": "object", "description": "Proveedor al que se retiene. Debe estar identificado; sus datos se usan en esta retención con las mismas\nreglas que el comprador de una factura. `9999999999999` (consumidor final) responde\n`422 IDENTIFICACION_INVALIDA`.\n", "additionalProperties": false, "required": [ "identificacion", "razonSocial" ], "properties": { "tipoIdentificacion": { "$ref": "#/components/schemas/CodigoTipoIdentificacionSujeto" }, "identificacion": { "type": "string", "description": "RUC (13 dígitos), cédula (10 dígitos), pasaporte o identificación del exterior. Si omites `tipoIdentificacion`, se deduce como en el comprador.", "minLength": 3, "maxLength": 20, "pattern": "^[A-Za-z0-9-]{3,20}$" }, "razonSocial": { "type": "string", "minLength": 3, "maxLength": 300 }, "email": { "type": "string", "format": "email", "maxLength": 255 }, "direccion": { "type": "string", "maxLength": 300 }, "telefono": { "type": "string", "maxLength": 30 } } }, "ItemSolicitud": { "type": "object", "additionalProperties": false, "required": [ "codigo", "descripcion", "cantidad", "precioUnitario" ], "properties": { "codigo": { "type": "string", "description": "Código principal del ítem. Si no existe en el catálogo de la empresa, se crea con estos datos.", "minLength": 1, "maxLength": 25 }, "codigoAuxiliar": { "type": "string", "maxLength": 25 }, "descripcion": { "type": "string", "description": "Descripción que se imprime en el comprobante (el catálogo no se modifica).", "minLength": 1, "maxLength": 300 }, "cantidad": { "type": "number", "description": "Cantidad, mayor que 0, con hasta 2 decimales (por ejemplo 1.25 kg).", "exclusiveMinimum": 0, "maximum": 999999999.99 }, "precioUnitario": { "type": "number", "description": "Precio unitario sin IVA, con hasta 4 decimales. Si tu sistema tiene el precio con IVA incluido (PVP),\nenvía PVP ÷ (1 + tarifa/100) redondeado a 4 decimales y, si quieres comparar con lo cobrado, usa\n`totalEsperado` (tolera 0.01).\n", "minimum": 0, "maximum": 999999999.9999 }, "descuento": { "type": "number", "description": "Descuento en dólares de la línea completa, con hasta 2 decimales. No puede superar cantidad × precio.", "minimum": 0, "default": 0 }, "iva": { "type": "number", "description": "Porcentaje de IVA del ítem. Se traduce al código del SRI (15 → 4, 5 → 5, 0 → 0, 13 → 10, 8 → 8; 12 → 2 y\n14 → 3 solo en notas de crédito de facturas de esas fechas). Obligatorio si no envías `codigoIva`.\n", "enum": [ 0, 5, 8, 12, 13, 14, 15 ] }, "codigoIva": { "$ref": "#/components/schemas/CodigoIva" }, "tipo": { "$ref": "#/components/schemas/TipoProducto" }, "detallesAdicionales": { "type": "array", "description": "Hasta 3 detalles adicionales del ítem.", "maxItems": 3, "items": { "$ref": "#/components/schemas/CampoAdicional" } } } }, "PagoSolicitud": { "type": "object", "additionalProperties": false, "required": [ "formaPago", "total" ], "properties": { "formaPago": { "$ref": "#/components/schemas/CodigoFormaPago" }, "total": { "type": "number", "description": "Valor pagado con esta forma, con hasta 2 decimales.", "exclusiveMinimum": 0, "maximum": 999999999.99 }, "plazo": { "type": "integer", "description": "Plazo de pago. Requiere `unidadTiempo`.", "minimum": 0, "maximum": 9999 }, "unidadTiempo": { "$ref": "#/components/schemas/UnidadTiempo" } } }, "FacturaSolicitud": { "type": "object", "additionalProperties": false, "required": [ "cliente", "items" ], "properties": { "establecimiento": { "$ref": "#/components/schemas/CodigoEstablecimiento" }, "puntoEmision": { "$ref": "#/components/schemas/CodigoPuntoEmision" }, "fechaEmision": { "type": "string", "format": "date", "description": "Fecha de emisión (hora de Ecuador). Por defecto, hoy. Solo se acepta la de hoy o la de ayer: el SRI exige\ntransmitir el comprobante al emitirlo. Otra fecha responde `422 FECHA_FUERA_DE_RANGO`.\n" }, "referencia": { "type": "string", "description": "Identificador del documento en tu sistema (por ejemplo, el número de pedido), para buscarlo después. No se imprime ni tiene que ser único.", "minLength": 1, "maxLength": 100 }, "cliente": { "$ref": "#/components/schemas/ClienteSolicitud" }, "items": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "$ref": "#/components/schemas/ItemSolicitud" } }, "formaPago": { "$ref": "#/components/schemas/CodigoFormaPago", "description": "Una sola forma de pago por el total de la factura. No se combina con `pagos`." }, "pagos": { "type": "array", "description": "Varias formas de pago. Deben sumar el total de la factura (±0.01). No se combina con `formaPago`.", "minItems": 1, "maxItems": 10, "items": { "$ref": "#/components/schemas/PagoSolicitud" } }, "propina": { "type": "number", "description": "Propina o cargo por servicio, con hasta 2 decimales. Por defecto 0.", "minimum": 0, "maximum": 999999999.99 }, "guiaRemision": { "$ref": "#/components/schemas/NumeroComprobante" }, "informacionAdicional": { "type": "array", "description": "Hasta 14 campos. Golem agrega el campo obligatorio \"RUC Proveedor\".", "maxItems": 14, "items": { "$ref": "#/components/schemas/CampoAdicional" } }, "totalEsperado": { "type": "number", "description": "Total que calculó tu sistema. Si difiere en más de 0.01 del cálculo de Golem, la factura no se emite (`422 TOTAL_NO_COINCIDE`).", "minimum": 0, "maximum": 999999999.99 } }, "description": "Envía `formaPago` o `pagos`, uno de los dos (si faltan ambos o vienen los dos, `400 VALIDACION`). Cada ítem\nnecesita `iva` o `codigoIva`. `cliente.razonSocial` es obligatoria salvo para consumidor final.\n" }, "FacturaReferenciaGolem": { "type": "object", "title": "Factura emitida en Golem", "additionalProperties": false, "required": [ "claveAcceso" ], "properties": { "claveAcceso": { "$ref": "#/components/schemas/ClaveAcceso" } } }, "DocumentoReferenciaExterno": { "type": "object", "title": "Documento emitido fuera de Golem", "additionalProperties": false, "required": [ "codDoc", "numero", "fechaEmision" ], "properties": { "codDoc": { "type": "string", "description": "Código del SRI del documento modificado. En esta versión, 01 (factura).", "enum": [ "01" ] }, "numero": { "$ref": "#/components/schemas/NumeroComprobante" }, "fechaEmision": { "type": "string", "format": "date" } } }, "NotaCreditoSolicitud": { "type": "object", "additionalProperties": false, "required": [ "documentoModificado", "motivo", "items" ], "properties": { "establecimiento": { "$ref": "#/components/schemas/CodigoEstablecimiento" }, "puntoEmision": { "$ref": "#/components/schemas/CodigoPuntoEmision" }, "fechaEmision": { "type": "string", "format": "date", "description": "Fecha de emisión. Por defecto, hoy; se acepta hoy o ayer, como en la factura. No puede ser anterior a la del documento modificado." }, "referencia": { "type": "string", "minLength": 1, "maxLength": 100 }, "documentoModificado": { "oneOf": [ { "$ref": "#/components/schemas/FacturaReferenciaGolem" }, { "$ref": "#/components/schemas/DocumentoReferenciaExterno" } ] }, "motivo": { "type": "string", "description": "Razón de la nota de crédito, como se imprime.", "minLength": 1, "maxLength": 300 }, "cliente": { "$ref": "#/components/schemas/ClienteSolicitud", "description": "Obligatorio si la factura se emitió fuera de Golem; si se emitió en Golem, se toma de ella y, si lo\nenvías, su identificación debe coincidir. No se admite consumidor final.\n" }, "items": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "$ref": "#/components/schemas/ItemSolicitud" } }, "informacionAdicional": { "type": "array", "maxItems": 14, "items": { "$ref": "#/components/schemas/CampoAdicional" } }, "totalEsperado": { "type": "number", "description": "Total (valor de la modificación) que calculó tu sistema. Si difiere en más de 0.01, no se emite.", "minimum": 0, "maximum": 999999999.99 } } }, "DocumentoSustentoSolicitud": { "type": "object", "additionalProperties": false, "required": [ "codDoc", "numero", "fechaEmision" ], "properties": { "codDoc": { "type": "string", "description": "Código del SRI del documento sustento (catálogo `tipos-documento-sustento`), por ejemplo 01 factura o 03 liquidación de compra.", "pattern": "^\\d{2,3}$" }, "numero": { "$ref": "#/components/schemas/NumeroComprobante" }, "fechaEmision": { "type": "string", "format": "date" } } }, "RetencionLineaSolicitud": { "type": "object", "additionalProperties": false, "required": [ "codigoImpuesto", "codigoRetencion", "baseImponible" ], "properties": { "codigoImpuesto": { "$ref": "#/components/schemas/CodigoImpuestoRetencion" }, "codigoRetencion": { "type": "string", "description": "Código del catálogo `retenciones-renta` o `retenciones-iva`, según el impuesto.", "minLength": 1, "maxLength": 6 }, "baseImponible": { "type": "number", "description": "Base imponible con hasta 2 decimales. En IVA es el valor del IVA del documento sustento.", "exclusiveMinimum": 0, "maximum": 999999999.99 }, "porcentaje": { "type": "number", "description": "Solo para códigos de porcentaje variable. En los demás se toma del catálogo; si lo envías, debe coincidir.", "minimum": 0, "maximum": 100 } } }, "RetencionSolicitud": { "type": "object", "additionalProperties": false, "required": [ "sujetoRetenido", "documentoSustento", "retenciones" ], "properties": { "establecimiento": { "$ref": "#/components/schemas/CodigoEstablecimiento" }, "puntoEmision": { "$ref": "#/components/schemas/CodigoPuntoEmision" }, "fechaEmision": { "type": "string", "format": "date", "description": "Fecha de emisión. Por defecto, hoy; se acepta hoy o ayer, como en la factura. No puede ser anterior a la\ndel documento sustento. Emite la retención dentro de los 5 días siguientes a recibir el documento sustento.\n" }, "referencia": { "type": "string", "minLength": 1, "maxLength": 100 }, "sujetoRetenido": { "$ref": "#/components/schemas/SujetoRetenidoSolicitud" }, "documentoSustento": { "$ref": "#/components/schemas/DocumentoSustentoSolicitud" }, "retenciones": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "$ref": "#/components/schemas/RetencionLineaSolicitud" } }, "informacionAdicional": { "type": "array", "maxItems": 14, "items": { "$ref": "#/components/schemas/CampoAdicional" } }, "totalEsperado": { "type": "number", "description": "Total retenido que calculó tu sistema. Si difiere en más de 0.01, no se emite.", "minimum": 0, "maximum": 999999999.99 } } }, "Mensaje": { "type": "object", "description": "Mensaje del SRI (recepción o autorización) o de Golem sobre el procesamiento del comprobante.", "required": [ "origen", "mensaje", "tipo" ], "properties": { "origen": { "type": "string", "enum": [ "SRI", "GOLEM" ] }, "identificador": { "type": [ "string", "null" ], "description": "Código del mensaje en el catálogo de errores del SRI." }, "mensaje": { "type": "string" }, "informacionAdicional": { "type": [ "string", "null" ] }, "tipo": { "type": "string", "enum": [ "ERROR", "ADVERTENCIA", "INFORMATIVO" ] } } }, "Anulacion": { "type": "object", "description": "Anulación hecha en Golem. No anula ante el SRI; `estadoSri` indica lo que declaró la empresa.", "required": [ "fecha" ], "properties": { "fecha": { "$ref": "#/components/schemas/Instante" }, "motivo": { "type": [ "string", "null" ] }, "estadoSri": { "type": [ "string", "null" ], "enum": [ "ANULADO", "PENDIENTE", "NO_APLICA", null ] } } }, "Enlaces": { "type": "object", "required": [ "self", "pdf", "xml" ], "properties": { "self": { "type": "string", "format": "uri" }, "pdf": { "type": [ "string", "null" ], "format": "uri", "description": "Solo cuando el RIDE se puede descargar (comprobante autorizado, o anulado que estuvo autorizado); si no, null." }, "xml": { "type": [ "string", "null" ], "format": "uri", "description": "Solo cuando el XML autorizado se puede descargar; si no, null." } } }, "ClienteComprobante": { "type": "object", "required": [ "tipoIdentificacion", "identificacion", "razonSocial" ], "properties": { "tipoIdentificacion": { "$ref": "#/components/schemas/CodigoTipoIdentificacion" }, "identificacion": { "type": "string" }, "razonSocial": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "direccion": { "type": [ "string", "null" ] }, "telefono": { "type": [ "string", "null" ] } } }, "ItemComprobante": { "type": "object", "required": [ "codigo", "descripcion", "cantidad", "precioUnitario", "descuento", "subtotal", "codigoIva", "tarifaIva", "valorIva" ], "properties": { "codigo": { "type": "string" }, "codigoAuxiliar": { "type": [ "string", "null" ] }, "descripcion": { "type": "string" }, "cantidad": { "type": "number" }, "precioUnitario": { "type": "number" }, "descuento": { "type": "number" }, "subtotal": { "type": "number", "description": "Precio total sin impuestos de la línea (cantidad × precio − descuento), redondeado a 2 decimales." }, "codigoIva": { "$ref": "#/components/schemas/CodigoIva" }, "tarifaIva": { "type": "number", "description": "Porcentaje de IVA aplicado." }, "valorIva": { "type": "number", "description": "IVA de la línea, redondeado a 2 decimales." }, "detallesAdicionales": { "type": "array", "items": { "$ref": "#/components/schemas/CampoAdicional" } } } }, "SubtotalIva": { "type": "object", "required": [ "codigoIva", "tarifa", "baseImponible", "valor" ], "properties": { "codigoIva": { "$ref": "#/components/schemas/CodigoIva" }, "tarifa": { "type": "number" }, "baseImponible": { "type": "number" }, "valor": { "type": "number" } } }, "Totales": { "type": "object", "description": "Totales calculados por Golem: el IVA de cada línea se redondea a 2 decimales (mitad hacia arriba) y el IVA\nde cada tarifa es la suma de sus líneas.\n", "required": [ "subtotal", "descuento", "subtotalesIva", "iva", "total" ], "properties": { "subtotal": { "type": "number", "description": "Total sin impuestos (suma de los subtotales de las líneas, ya descontados)." }, "descuento": { "type": "number", "description": "Suma de los descuentos de las líneas." }, "subtotalesIva": { "type": "array", "items": { "$ref": "#/components/schemas/SubtotalIva" } }, "iva": { "type": "number" }, "propina": { "type": "number" }, "total": { "type": "number" } } }, "PagoComprobante": { "type": "object", "required": [ "formaPago", "total" ], "properties": { "formaPago": { "$ref": "#/components/schemas/CodigoFormaPago" }, "total": { "type": "number" }, "plazo": { "type": [ "integer", "null" ] }, "unidadTiempo": { "type": [ "string", "null" ], "enum": [ "DIAS", "MESES", "ANIOS", null ] } } }, "DocumentoModificado": { "type": "object", "required": [ "codDoc", "numero", "fechaEmision" ], "properties": { "codDoc": { "type": "string", "description": "Código del SRI del documento (01 factura, 03 liquidación de compra, …)." }, "numero": { "$ref": "#/components/schemas/NumeroComprobante" }, "fechaEmision": { "type": "string", "format": "date" }, "claveAcceso": { "type": [ "string", "null" ], "description": "Clave de acceso de la factura si se emitió en Golem." } } }, "RetencionLinea": { "type": "object", "required": [ "codigoImpuesto", "codigoRetencion", "baseImponible", "porcentaje", "valorRetenido" ], "properties": { "codigoImpuesto": { "$ref": "#/components/schemas/CodigoImpuestoRetencion" }, "codigoRetencion": { "type": "string" }, "baseImponible": { "type": "number" }, "porcentaje": { "type": "number" }, "valorRetenido": { "type": "number" } } }, "ComprobanteBase": { "type": "object", "required": [ "tipo", "codDoc", "claveAcceso", "numero", "estado", "ambiente", "fechaEmision", "fechaActualizacion", "establecimiento", "puntoEmision", "total", "mensajes", "enlaces" ], "properties": { "tipo": { "$ref": "#/components/schemas/TipoComprobante" }, "codDoc": { "$ref": "#/components/schemas/CodigoDocumento" }, "claveAcceso": { "$ref": "#/components/schemas/ClaveAcceso" }, "numero": { "$ref": "#/components/schemas/NumeroComprobante" }, "estado": { "$ref": "#/components/schemas/EstadoComprobante" }, "ambiente": { "$ref": "#/components/schemas/Ambiente" }, "fechaEmision": { "type": "string", "format": "date" }, "fechaEnvio": { "type": [ "string", "null" ], "format": "date-time", "description": "Cuándo el SRI recibió el comprobante; null si aún no se envía." }, "fechaAutorizacion": { "type": [ "string", "null" ], "format": "date-time" }, "numeroAutorizacion": { "type": [ "string", "null" ], "description": "Número de autorización del SRI (igual a la clave de acceso); null si no está autorizado." }, "fechaActualizacion": { "type": "string", "format": "date-time", "description": "Último cambio del comprobante (estado, anulación u otro dato), con milisegundos. Úsalo como `cambiadoDesde` en el listado." }, "establecimiento": { "$ref": "#/components/schemas/CodigoEstablecimiento" }, "puntoEmision": { "$ref": "#/components/schemas/CodigoPuntoEmision" }, "referencia": { "type": [ "string", "null" ] }, "origen": { "description": "Canal de creación; null en comprobantes anteriores a esta versión.", "oneOf": [ { "$ref": "#/components/schemas/Origen" }, { "type": "null" } ] }, "total": { "type": "number", "description": "Importe total (en la retención, el total retenido)." }, "mensajes": { "type": "array", "items": { "$ref": "#/components/schemas/Mensaje" } }, "anulacion": { "oneOf": [ { "$ref": "#/components/schemas/Anulacion" }, { "type": "null" } ] }, "informacionAdicional": { "type": "array", "items": { "$ref": "#/components/schemas/CampoAdicional" } }, "enlaces": { "$ref": "#/components/schemas/Enlaces" } } }, "Factura": { "title": "Factura", "allOf": [ { "$ref": "#/components/schemas/ComprobanteBase" }, { "type": "object", "required": [ "tipo", "cliente", "items", "pagos", "totales" ], "properties": { "tipo": { "const": "FACTURA" }, "codDoc": { "const": "01" }, "cliente": { "$ref": "#/components/schemas/ClienteComprobante" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ItemComprobante" } }, "pagos": { "type": "array", "items": { "$ref": "#/components/schemas/PagoComprobante" } }, "guiaRemision": { "type": [ "string", "null" ] }, "totales": { "$ref": "#/components/schemas/Totales" } } } ] }, "NotaCredito": { "title": "Nota de crédito", "allOf": [ { "$ref": "#/components/schemas/ComprobanteBase" }, { "type": "object", "required": [ "tipo", "cliente", "documentoModificado", "motivo", "items", "totales" ], "properties": { "tipo": { "const": "NOTA_CREDITO" }, "codDoc": { "const": "04" }, "cliente": { "$ref": "#/components/schemas/ClienteComprobante" }, "documentoModificado": { "$ref": "#/components/schemas/DocumentoModificado" }, "motivo": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ItemComprobante" } }, "totales": { "$ref": "#/components/schemas/Totales" } } } ] }, "Retencion": { "title": "Comprobante de retención", "allOf": [ { "$ref": "#/components/schemas/ComprobanteBase" }, { "type": "object", "required": [ "tipo", "sujetoRetenido", "periodoFiscal", "documentoSustento", "retenciones" ], "properties": { "tipo": { "const": "RETENCION" }, "codDoc": { "const": "07" }, "sujetoRetenido": { "$ref": "#/components/schemas/ClienteComprobante" }, "periodoFiscal": { "type": "string", "description": "Año y mes, `yyyy-MM` (en el XML del SRI va como `MM/yyyy`).", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$" }, "documentoSustento": { "$ref": "#/components/schemas/DocumentoModificado" }, "retenciones": { "type": "array", "items": { "$ref": "#/components/schemas/RetencionLinea" } } } } ] }, "Comprobante": { "oneOf": [ { "$ref": "#/components/schemas/Factura" }, { "$ref": "#/components/schemas/NotaCredito" }, { "$ref": "#/components/schemas/Retencion" } ], "discriminator": { "propertyName": "tipo", "mapping": { "FACTURA": "#/components/schemas/Factura", "NOTA_CREDITO": "#/components/schemas/NotaCredito", "RETENCION": "#/components/schemas/Retencion" } } }, "ResumenComprobante": { "type": "object", "required": [ "tipo", "codDoc", "claveAcceso", "numero", "estado", "ambiente", "fechaEmision", "fechaActualizacion", "receptor", "total" ], "properties": { "tipo": { "$ref": "#/components/schemas/TipoComprobante" }, "codDoc": { "$ref": "#/components/schemas/CodigoDocumento" }, "claveAcceso": { "$ref": "#/components/schemas/ClaveAcceso" }, "numero": { "$ref": "#/components/schemas/NumeroComprobante" }, "estado": { "$ref": "#/components/schemas/EstadoComprobante" }, "ambiente": { "$ref": "#/components/schemas/Ambiente" }, "fechaEmision": { "type": "string", "format": "date" }, "fechaAutorizacion": { "type": [ "string", "null" ], "format": "date-time" }, "fechaActualizacion": { "type": "string", "format": "date-time" }, "receptor": { "type": "object", "required": [ "identificacion", "razonSocial" ], "properties": { "identificacion": { "type": "string" }, "razonSocial": { "type": "string" } } }, "total": { "type": "number" }, "referencia": { "type": [ "string", "null" ] }, "origen": { "oneOf": [ { "$ref": "#/components/schemas/Origen" }, { "type": "null" } ] } } }, "Paginacion": { "type": "object", "required": [ "pagina", "porPagina", "total", "paginas" ], "properties": { "pagina": { "type": "integer" }, "porPagina": { "type": "integer" }, "total": { "type": "integer", "description": "Comprobantes que cumplen el filtro." }, "paginas": { "type": "integer" } } }, "ListaComprobantes": { "type": "object", "required": [ "datos", "paginacion" ], "properties": { "datos": { "type": "array", "items": { "$ref": "#/components/schemas/ResumenComprobante" } }, "paginacion": { "$ref": "#/components/schemas/Paginacion" } } }, "EnvioCorreo": { "type": "object", "required": [ "claveAcceso", "destinatario", "mensaje" ], "properties": { "claveAcceso": { "$ref": "#/components/schemas/ClaveAcceso" }, "destinatario": { "type": "string", "description": "Correo de destino, enmascarado. En pruebas, el buzón de Golem." }, "mensaje": { "type": "string" } } }, "PuntoEmisionEmpresa": { "type": "object", "required": [ "codigo", "siguientesSecuenciales" ], "properties": { "codigo": { "$ref": "#/components/schemas/CodigoPuntoEmision" }, "descripcion": { "type": [ "string", "null" ] }, "siguientesSecuenciales": { "type": "object", "description": "Próximo secuencial de cada tipo en el ambiente del token.", "required": [ "factura", "notaCredito", "retencion" ], "properties": { "factura": { "type": "integer" }, "notaCredito": { "type": "integer" }, "retencion": { "type": "integer" } } } } }, "ReferenciaPunto": { "type": "object", "required": [ "establecimiento", "puntoEmision" ], "properties": { "establecimiento": { "$ref": "#/components/schemas/CodigoEstablecimiento" }, "puntoEmision": { "$ref": "#/components/schemas/CodigoPuntoEmision" } } }, "EstablecimientoEmpresa": { "type": "object", "required": [ "codigo", "matriz", "puntosEmision" ], "properties": { "codigo": { "$ref": "#/components/schemas/CodigoEstablecimiento" }, "descripcion": { "type": [ "string", "null" ] }, "direccion": { "type": [ "string", "null" ] }, "matriz": { "type": "boolean" }, "puntosEmision": { "type": "array", "items": { "$ref": "#/components/schemas/PuntoEmisionEmpresa" } } } }, "Empresa": { "type": "object", "required": [ "ruc", "razonSocial", "regimen", "obligadoContabilidad", "contribuyenteEspecial", "agenteRetencion", "ambiente", "creditosDisponibles", "firma", "token", "establecimientos" ], "properties": { "ruc": { "type": "string" }, "razonSocial": { "type": "string" }, "nombreComercial": { "type": [ "string", "null" ] }, "regimen": { "type": "string", "description": "Régimen tributario, que define la leyenda de los comprobantes.", "enum": [ "GENERAL", "RIMPE_EMPRENDEDOR", "RIMPE_NEGOCIO_POPULAR" ] }, "obligadoContabilidad": { "type": "boolean" }, "contribuyenteEspecial": { "type": "boolean", "description": "Si la empresa es contribuyente especial (igual que en `GET /ruc/{ruc}`)." }, "resolucionContribuyenteEspecial": { "type": [ "string", "null" ], "description": "Número de resolución de contribuyente especial que se imprime en los comprobantes." }, "agenteRetencion": { "type": "boolean", "description": "Si la empresa es agente de retención (igual que en `GET /ruc/{ruc}`)." }, "resolucionAgenteRetencion": { "type": [ "string", "null" ], "description": "Número de resolución de agente de retención que se imprime en los comprobantes." }, "ambiente": { "$ref": "#/components/schemas/Ambiente" }, "creditosDisponibles": { "type": "integer" }, "firma": { "type": "object", "required": [ "configurada", "vigente" ], "properties": { "configurada": { "type": "boolean" }, "vigente": { "type": "boolean" }, "vence": { "type": [ "string", "null" ], "format": "date" }, "porVencer": { "type": "boolean", "description": "Vence en 30 días o menos." } } }, "token": { "type": "object", "required": [ "nombre", "prefijo", "ambiente", "puntoPorDefecto", "puntosPermitidos" ], "properties": { "nombre": { "type": "string" }, "prefijo": { "type": "string", "description": "Inicio del token, para reconocerlo." }, "ambiente": { "$ref": "#/components/schemas/Ambiente" }, "puntoPorDefecto": { "description": "Punto que se usa cuando la emisión no indica `establecimiento` y `puntoEmision`; null si no tiene.", "oneOf": [ { "$ref": "#/components/schemas/ReferenciaPunto" }, { "type": "null" } ] }, "puntosPermitidos": { "description": "Puntos en los que el token puede emitir. null: todos los puntos de la empresa. Una lista vacía\nsignifica que sus puntos ya no existen y el token no puede emitir (`403 PUNTO_NO_PERMITIDO`).\n", "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/ReferenciaPunto" } }, { "type": "null" } ] } } }, "establecimientos": { "type": "array", "items": { "$ref": "#/components/schemas/EstablecimientoEmpresa" } } } }, "Ruc": { "type": "object", "required": [ "ruc", "razonSocial", "activo" ], "properties": { "ruc": { "type": "string" }, "razonSocial": { "type": "string" }, "nombreComercial": { "type": [ "string", "null" ] }, "estado": { "type": [ "string", "null" ], "description": "Estado del RUC según el SRI (por ejemplo ACTIVO o SUSPENDIDO)." }, "activo": { "type": "boolean" }, "tipoPersona": { "type": [ "string", "null" ], "enum": [ "NATURAL", "JURIDICA", null ] }, "regimen": { "type": [ "string", "null" ], "enum": [ "GENERAL", "RIMPE_EMPRENDEDOR", "RIMPE_NEGOCIO_POPULAR", null ] }, "obligadoContabilidad": { "type": "boolean" }, "agenteRetencion": { "type": "boolean" }, "contribuyenteEspecial": { "type": "boolean" }, "direccionMatriz": { "type": [ "string", "null" ] }, "establecimientos": { "type": "array", "items": { "type": "object", "required": [ "numero", "abierto", "matriz" ], "properties": { "numero": { "type": "string" }, "nombreComercial": { "type": [ "string", "null" ] }, "direccion": { "type": [ "string", "null" ] }, "abierto": { "type": "boolean" }, "matriz": { "type": "boolean" } } } } } }, "CatalogoResumen": { "type": "object", "required": [ "nombre", "descripcion" ], "properties": { "nombre": { "$ref": "#/components/schemas/NombreCatalogo" }, "descripcion": { "type": "string" }, "fuente": { "type": "string" } } }, "ElementoCatalogo": { "type": "object", "required": [ "codigo", "nombre", "vigente" ], "properties": { "codigo": { "type": "string" }, "nombre": { "type": "string" }, "porcentaje": { "type": [ "number", "null" ], "description": "Porcentaje (tarifas de IVA y retenciones); null en los códigos de porcentaje variable." }, "porcentajeVariable": { "type": "boolean", "description": "En retenciones, true si el porcentaje lo indica el emisor en `porcentaje` de la línea." }, "vigente": { "type": "boolean" }, "vigenteDesde": { "type": [ "string", "null" ], "format": "date" }, "vigenteHasta": { "type": [ "string", "null" ], "format": "date" } } }, "Catalogo": { "type": "object", "required": [ "nombre", "descripcion", "datos" ], "properties": { "nombre": { "$ref": "#/components/schemas/NombreCatalogo" }, "descripcion": { "type": "string" }, "fuente": { "type": "string" }, "datos": { "type": "array", "items": { "$ref": "#/components/schemas/ElementoCatalogo" } } } }, "DetalleError": { "type": "object", "required": [ "campo", "codigo", "mensaje" ], "properties": { "campo": { "type": "string", "description": "Ruta del campo en el JSON, por ejemplo `items[0].cantidad`." }, "codigo": { "type": "string", "description": "CAMPO_REQUERIDO, CAMPO_DESCONOCIDO, TIPO_INVALIDO, FORMATO_INVALIDO, VALOR_INVALIDO, LONGITUD_INVALIDA o DECIMALES_EXCEDIDOS." }, "mensaje": { "type": "string" } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "codigo", "mensaje", "campo", "detalles", "requestId" ], "properties": { "codigo": { "type": "string", "description": "Código estable del error. Ver la tabla de errores en la documentación." }, "mensaje": { "type": "string", "description": "Explicación en español para la persona que integra." }, "campo": { "type": [ "string", "null" ], "description": "Campo o cabecera que causó el error, si aplica." }, "detalles": { "type": "array", "items": { "$ref": "#/components/schemas/DetalleError" } }, "requestId": { "type": "string" } } } } } }, "examples": { "FacturaSolicitudMinima": { "summary": "Factura mínima (ejemplo de golem.ec)", "value": { "establecimiento": "001", "puntoEmision": "001", "cliente": { "identificacion": "0990000000001", "razonSocial": "CLIENTE DEMO S.A.", "email": "facturas@cliente-demo.ec" }, "items": [ { "codigo": "P-001", "descripcion": "Producto de ejemplo", "cantidad": 10, "precioUnitario": 7.8, "iva": 15 } ], "formaPago": "20" } }, "FacturaSolicitudCompleta": { "summary": "Factura con descuento, dos tarifas, dos pagos y referencia", "value": { "establecimiento": "001", "puntoEmision": "001", "referencia": "PED-2026-00481", "cliente": { "tipoIdentificacion": "05", "identificacion": "1700000001", "razonSocial": "PERSONA DEMO", "email": "persona.demo@correo-demo.ec", "direccion": "Av. Amazonas N24-03, Quito", "telefono": "022000000" }, "items": [ { "codigo": "SERV-01", "descripcion": "Mantenimiento mensual", "cantidad": 1, "precioUnitario": 120, "descuento": 12, "iva": 15, "tipo": "SERVICIO" }, { "codigo": "LIB-07", "descripcion": "Libro técnico", "cantidad": 2, "precioUnitario": 15.5, "codigoIva": "0", "detallesAdicionales": [ { "nombre": "Edición", "valor": "2026" } ] } ], "pagos": [ { "formaPago": "19", "total": 100 }, { "formaPago": "20", "total": 55.2, "plazo": 30, "unidadTiempo": "DIAS" } ], "informacionAdicional": [ { "nombre": "Pedido", "valor": "PED-2026-00481" } ], "totalEsperado": 155.2 } }, "FacturaSolicitudConsumidorFinal": { "summary": "Factura a consumidor final", "value": { "cliente": { "identificacion": "9999999999999" }, "items": [ { "codigo": "CAFE-01", "descripcion": "Café de especialidad 250 g", "cantidad": 1, "precioUnitario": 8.5, "iva": 15 } ], "formaPago": "01" } }, "NotaCreditoSolicitudGolem": { "summary": "Nota de crédito de una factura emitida en Golem", "value": { "establecimiento": "001", "puntoEmision": "001", "referencia": "DEV-2026-0012", "documentoModificado": { "claveAcceso": "2409202601179000000000120010010000001481234567815" }, "motivo": "Devolución de 2 unidades", "items": [ { "codigo": "P-001", "descripcion": "Producto de ejemplo", "cantidad": 2, "precioUnitario": 7.8, "iva": 15 } ] } }, "NotaCreditoSolicitudExterna": { "summary": "Nota de crédito de una factura de 2023 emitida fuera de Golem (IVA 12 %)", "value": { "documentoModificado": { "codDoc": "01", "numero": "001-001-000004210", "fechaEmision": "2023-11-14" }, "motivo": "Descuento posterior a la venta", "cliente": { "tipoIdentificacion": "04", "identificacion": "0990000000001", "razonSocial": "CLIENTE DEMO S.A.", "email": "facturas@cliente-demo.ec" }, "items": [ { "codigo": "DESC-2023", "descripcion": "Descuento sobre factura 001-001-000004210", "cantidad": 1, "precioUnitario": 25, "iva": 12 } ] } }, "RetencionSolicitud": { "summary": "Retención de renta 1.75 % e IVA 30 % sobre una factura de proveedor", "value": { "establecimiento": "001", "puntoEmision": "001", "referencia": "CXP-2026-0931", "sujetoRetenido": { "tipoIdentificacion": "04", "identificacion": "0990000000001", "razonSocial": "PROVEEDOR DEMO S.A.", "email": "cobranzas@proveedor-demo.ec" }, "documentoSustento": { "codDoc": "01", "numero": "002-001-000004521", "fechaEmision": "2026-09-22" }, "retenciones": [ { "codigoImpuesto": "1", "codigoRetencion": "312", "baseImponible": 1000 }, { "codigoImpuesto": "2", "codigoRetencion": "1", "baseImponible": 150 } ], "totalEsperado": 62.5 } }, "FacturaAutorizada": { "summary": "Factura autorizada", "value": { "tipo": "FACTURA", "codDoc": "01", "claveAcceso": "2409202601179000000000120010010000001481234567815", "numero": "001-001-000000148", "estado": "AUTORIZADO", "ambiente": "PRODUCCION", "fechaEmision": "2026-09-24", "fechaEnvio": "2026-09-24T10:42:28-05:00", "fechaAutorizacion": "2026-09-24T10:42:31-05:00", "numeroAutorizacion": "2409202601179000000000120010010000001481234567815", "fechaActualizacion": "2026-09-24T10:42:33.512-05:00", "establecimiento": "001", "puntoEmision": "001", "referencia": null, "origen": "API", "total": 89.7, "cliente": { "tipoIdentificacion": "04", "identificacion": "0990000000001", "razonSocial": "CLIENTE DEMO S.A.", "email": "facturas@cliente-demo.ec", "direccion": null, "telefono": null }, "items": [ { "codigo": "P-001", "codigoAuxiliar": null, "descripcion": "Producto de ejemplo", "cantidad": 10, "precioUnitario": 7.8, "descuento": 0, "subtotal": 78, "codigoIva": "4", "tarifaIva": 15, "valorIva": 11.7, "detallesAdicionales": [] } ], "pagos": [ { "formaPago": "20", "total": 89.7, "plazo": null, "unidadTiempo": null } ], "guiaRemision": null, "totales": { "subtotal": 78, "descuento": 0, "subtotalesIva": [ { "codigoIva": "4", "tarifa": 15, "baseImponible": 78, "valor": 11.7 } ], "iva": 11.7, "propina": 0, "total": 89.7 }, "mensajes": [], "anulacion": null, "informacionAdicional": [ { "nombre": "RUC Proveedor", "valor": "0195113076001" } ], "enlaces": { "self": "https://api.golem.ec/v1/comprobantes/2409202601179000000000120010010000001481234567815", "pdf": "https://api.golem.ec/v1/comprobantes/2409202601179000000000120010010000001481234567815/pdf", "xml": "https://api.golem.ec/v1/comprobantes/2409202601179000000000120010010000001481234567815/xml" } } }, "FacturaEnProceso": { "summary": "Factura en proceso (el SRI aún no responde)", "value": { "tipo": "FACTURA", "codDoc": "01", "claveAcceso": "2609202601179000000000120010010000001498765432115", "numero": "001-001-000000149", "estado": "EN_PROCESO", "ambiente": "PRODUCCION", "fechaEmision": "2026-09-26", "fechaEnvio": "2026-09-26T09:15:04-05:00", "fechaAutorizacion": null, "numeroAutorizacion": null, "fechaActualizacion": "2026-09-26T09:15:04.120-05:00", "establecimiento": "001", "puntoEmision": "001", "referencia": "PED-2026-00482", "origen": "API", "total": 89.7, "cliente": { "tipoIdentificacion": "04", "identificacion": "0990000000001", "razonSocial": "CLIENTE DEMO S.A.", "email": "facturas@cliente-demo.ec", "direccion": null, "telefono": null }, "items": [ { "codigo": "P-001", "codigoAuxiliar": null, "descripcion": "Producto de ejemplo", "cantidad": 10, "precioUnitario": 7.8, "descuento": 0, "subtotal": 78, "codigoIva": "4", "tarifaIva": 15, "valorIva": 11.7, "detallesAdicionales": [] } ], "pagos": [ { "formaPago": "20", "total": 89.7, "plazo": null, "unidadTiempo": null } ], "guiaRemision": null, "totales": { "subtotal": 78, "descuento": 0, "subtotalesIva": [ { "codigoIva": "4", "tarifa": 15, "baseImponible": 78, "valor": 11.7 } ], "iva": 11.7, "propina": 0, "total": 89.7 }, "mensajes": [], "anulacion": null, "informacionAdicional": [], "enlaces": { "self": "https://api.golem.ec/v1/comprobantes/2609202601179000000000120010010000001498765432115", "pdf": null, "xml": null } } }, "FacturaDevuelta": { "summary": "Factura devuelta por el SRI (el crédito vuelve al saldo)", "value": { "tipo": "FACTURA", "codDoc": "01", "claveAcceso": "2609202601179000000000120010010000001501122334419", "numero": "001-001-000000150", "estado": "DEVUELTO", "ambiente": "PRODUCCION", "fechaEmision": "2026-09-26", "fechaEnvio": "2026-09-26T09:20:11-05:00", "fechaAutorizacion": null, "numeroAutorizacion": null, "fechaActualizacion": "2026-09-26T09:20:12.845-05:00", "establecimiento": "001", "puntoEmision": "001", "referencia": "PED-2026-00483", "origen": "API", "total": 11.5, "cliente": { "tipoIdentificacion": "04", "identificacion": "0990000000001", "razonSocial": "CLIENTE DEMO S.A.", "email": "facturas@cliente-demo.ec", "direccion": null, "telefono": null }, "items": [ { "codigo": "P-002", "codigoAuxiliar": null, "descripcion": "Servicio de ejemplo", "cantidad": 1, "precioUnitario": 10, "descuento": 0, "subtotal": 10, "codigoIva": "4", "tarifaIva": 15, "valorIva": 1.5, "detallesAdicionales": [] } ], "pagos": [ { "formaPago": "20", "total": 11.5, "plazo": null, "unidadTiempo": null } ], "guiaRemision": null, "totales": { "subtotal": 10, "descuento": 0, "subtotalesIva": [ { "codigoIva": "4", "tarifa": 15, "baseImponible": 10, "valor": 1.5 } ], "iva": 1.5, "propina": 0, "total": 11.5 }, "mensajes": [ { "origen": "SRI", "identificador": "56", "mensaje": "ESTABLECIMIENTO CERRADO", "informacionAdicional": "El establecimiento 001 del RUC 1790000000001 está cerrado en el catastro.", "tipo": "ERROR" } ], "anulacion": null, "informacionAdicional": [], "enlaces": { "self": "https://api.golem.ec/v1/comprobantes/2609202601179000000000120010010000001501122334419", "pdf": null, "xml": null } } }, "NotaCreditoAutorizada": { "summary": "Nota de crédito autorizada", "value": { "tipo": "NOTA_CREDITO", "codDoc": "04", "claveAcceso": "2609202604179000000000120010010000000095550123411", "numero": "001-001-000000009", "estado": "AUTORIZADO", "ambiente": "PRODUCCION", "fechaEmision": "2026-09-26", "fechaEnvio": "2026-09-26T11:02:40-05:00", "fechaAutorizacion": "2026-09-26T11:02:43-05:00", "numeroAutorizacion": "2609202604179000000000120010010000000095550123411", "fechaActualizacion": "2026-09-26T11:02:44.087-05:00", "establecimiento": "001", "puntoEmision": "001", "referencia": "DEV-2026-0012", "origen": "API", "total": 17.94, "cliente": { "tipoIdentificacion": "04", "identificacion": "0990000000001", "razonSocial": "CLIENTE DEMO S.A.", "email": "facturas@cliente-demo.ec", "direccion": null, "telefono": null }, "documentoModificado": { "codDoc": "01", "numero": "001-001-000000148", "fechaEmision": "2026-09-24", "claveAcceso": "2409202601179000000000120010010000001481234567815" }, "motivo": "Devolución de 2 unidades", "items": [ { "codigo": "P-001", "codigoAuxiliar": null, "descripcion": "Producto de ejemplo", "cantidad": 2, "precioUnitario": 7.8, "descuento": 0, "subtotal": 15.6, "codigoIva": "4", "tarifaIva": 15, "valorIva": 2.34, "detallesAdicionales": [] } ], "totales": { "subtotal": 15.6, "descuento": 0, "subtotalesIva": [ { "codigoIva": "4", "tarifa": 15, "baseImponible": 15.6, "valor": 2.34 } ], "iva": 2.34, "total": 17.94 }, "mensajes": [], "anulacion": null, "informacionAdicional": [ { "nombre": "RUC Proveedor", "valor": "0195113076001" } ], "enlaces": { "self": "https://api.golem.ec/v1/comprobantes/2609202604179000000000120010010000000095550123411", "pdf": "https://api.golem.ec/v1/comprobantes/2609202604179000000000120010010000000095550123411/pdf", "xml": "https://api.golem.ec/v1/comprobantes/2609202604179000000000120010010000000095550123411/xml" } } }, "RetencionAutorizada": { "summary": "Comprobante de retención autorizado", "value": { "tipo": "RETENCION", "codDoc": "07", "claveAcceso": "2609202607179000000000120010010000000223141592611", "numero": "001-001-000000022", "estado": "AUTORIZADO", "ambiente": "PRODUCCION", "fechaEmision": "2026-09-26", "fechaEnvio": "2026-09-26T12:10:05-05:00", "fechaAutorizacion": "2026-09-26T12:10:08-05:00", "numeroAutorizacion": "2609202607179000000000120010010000000223141592611", "fechaActualizacion": "2026-09-26T12:10:09.301-05:00", "establecimiento": "001", "puntoEmision": "001", "referencia": "CXP-2026-0931", "origen": "API", "total": 62.5, "sujetoRetenido": { "tipoIdentificacion": "04", "identificacion": "0990000000001", "razonSocial": "PROVEEDOR DEMO S.A.", "email": "cobranzas@proveedor-demo.ec", "direccion": null, "telefono": null }, "periodoFiscal": "2026-09", "documentoSustento": { "codDoc": "01", "numero": "002-001-000004521", "fechaEmision": "2026-09-22", "claveAcceso": null }, "retenciones": [ { "codigoImpuesto": "1", "codigoRetencion": "312", "baseImponible": 1000, "porcentaje": 1.75, "valorRetenido": 17.5 }, { "codigoImpuesto": "2", "codigoRetencion": "1", "baseImponible": 150, "porcentaje": 30, "valorRetenido": 45 } ], "mensajes": [], "anulacion": null, "informacionAdicional": [ { "nombre": "RUC Proveedor", "valor": "0195113076001" } ], "enlaces": { "self": "https://api.golem.ec/v1/comprobantes/2609202607179000000000120010010000000223141592611", "pdf": "https://api.golem.ec/v1/comprobantes/2609202607179000000000120010010000000223141592611/pdf", "xml": "https://api.golem.ec/v1/comprobantes/2609202607179000000000120010010000000223141592611/xml" } } }, "ListaComprobantes": { "summary": "Primera página de facturas de septiembre", "value": { "datos": [ { "tipo": "FACTURA", "codDoc": "01", "claveAcceso": "2609202601179000000000120010010000001498765432115", "numero": "001-001-000000149", "estado": "EN_PROCESO", "ambiente": "PRODUCCION", "fechaEmision": "2026-09-26", "fechaAutorizacion": null, "fechaActualizacion": "2026-09-26T09:15:04.120-05:00", "receptor": { "identificacion": "0990000000001", "razonSocial": "CLIENTE DEMO S.A." }, "total": 89.7, "referencia": "PED-2026-00482", "origen": "API" }, { "tipo": "FACTURA", "codDoc": "01", "claveAcceso": "2409202601179000000000120010010000001481234567815", "numero": "001-001-000000148", "estado": "AUTORIZADO", "ambiente": "PRODUCCION", "fechaEmision": "2026-09-24", "fechaAutorizacion": "2026-09-24T10:42:31-05:00", "fechaActualizacion": "2026-09-24T10:42:33.512-05:00", "receptor": { "identificacion": "0990000000001", "razonSocial": "CLIENTE DEMO S.A." }, "total": 89.7, "referencia": null, "origen": "API" }, { "tipo": "FACTURA", "codDoc": "01", "claveAcceso": "2009202601179000000000120010010000001472468135717", "numero": "001-001-000000147", "estado": "AUTORIZADO", "ambiente": "PRODUCCION", "fechaEmision": "2026-09-20", "fechaAutorizacion": "2026-09-20T16:05:12-05:00", "fechaActualizacion": "2026-09-20T16:05:13.004-05:00", "receptor": { "identificacion": "1700000001001", "razonSocial": "PERSONA DEMO" }, "total": 23, "referencia": null, "origen": "APP" } ], "paginacion": { "pagina": 1, "porPagina": 20, "total": 3, "paginas": 1 } } }, "Empresa": { "summary": "Empresa de un token de producción", "value": { "ruc": "1790000000001", "razonSocial": "TU EMPRESA S.A.", "nombreComercial": "TU EMPRESA", "regimen": "GENERAL", "obligadoContabilidad": true, "contribuyenteEspecial": false, "resolucionContribuyenteEspecial": null, "agenteRetencion": true, "resolucionAgenteRetencion": "1", "ambiente": "PRODUCCION", "creditosDisponibles": 48, "firma": { "configurada": true, "vigente": true, "vence": "2027-03-01", "porVencer": false }, "token": { "nombre": "ERP principal", "prefijo": "glm_prod_7Qx4", "ambiente": "PRODUCCION", "puntoPorDefecto": { "establecimiento": "001", "puntoEmision": "001" }, "puntosPermitidos": null }, "establecimientos": [ { "codigo": "001", "descripcion": "Matriz", "direccion": "Av. Amazonas N24-03 y Colón, Quito", "matriz": true, "puntosEmision": [ { "codigo": "001", "descripcion": "Caja 1", "siguientesSecuenciales": { "factura": 150, "notaCredito": 10, "retencion": 23 } }, { "codigo": "002", "descripcion": "Tienda en línea", "siguientesSecuenciales": { "factura": 1, "notaCredito": 1, "retencion": 1 } } ] } ] } }, "Ruc": { "summary": "Entidad pública activa (Servicio de Rentas Internas)", "description": "Respuesta del catastro del SRI para el RUC 1760013210001. La lista de establecimientos está abreviada: el SRI registra 86 establecimientos para este RUC y la respuesta los incluye todos, abiertos y cerrados.", "value": { "ruc": "1760013210001", "razonSocial": "SERVICIO DE RENTAS INTERNAS", "nombreComercial": null, "estado": "ACTIVO", "activo": true, "tipoPersona": "JURIDICA", "regimen": "GENERAL", "obligadoContabilidad": true, "agenteRetencion": true, "contribuyenteEspecial": true, "direccionMatriz": "PICHINCHA / QUITO / IÑAQUITO / AVENIDA AMAZONAS S/N Y UNIÓN NACIONAL DE PERIODISTAS", "establecimientos": [ { "numero": "001", "nombreComercial": null, "direccion": "PICHINCHA / QUITO / MARISCAL SUCRE / PÁEZ N22-53 Y RAMIREZ DÁVALOS", "abierto": true, "matriz": false }, { "numero": "002", "nombreComercial": null, "direccion": "GUAYAS / GUAYAQUIL / ROCAFUERTE / AV. 10 DE AGOSTO 212 Y PEDRO CARBO Y PICHINCHA", "abierto": false, "matriz": false }, { "numero": "059", "nombreComercial": null, "direccion": "PICHINCHA / QUITO / IÑAQUITO / AVENIDA AMAZONAS S/N Y UNIÓN NACIONAL DE PERIODISTAS", "abierto": true, "matriz": true } ] } }, "CatalogoFormasPago": { "summary": "Formas de pago vigentes", "value": { "nombre": "formas-pago", "descripcion": "Formas de pago de una factura.", "fuente": "Ficha técnica de comprobantes electrónicos del SRI, tabla 24.", "datos": [ { "codigo": "01", "nombre": "SIN UTILIZACION DEL SISTEMA FINANCIERO", "vigente": true }, { "codigo": "15", "nombre": "COMPENSACION DE DEUDAS", "vigente": true }, { "codigo": "16", "nombre": "TARJETAS DE DEBITO", "vigente": true }, { "codigo": "17", "nombre": "DINERO ELECTRONICO", "vigente": true }, { "codigo": "18", "nombre": "TARJETA PREPAGO", "vigente": true }, { "codigo": "19", "nombre": "TARJETA DE CREDITO", "vigente": true }, { "codigo": "20", "nombre": "OTROS CON UTILIZACION DEL SISTEMA FINANCIERO", "vigente": true }, { "codigo": "21", "nombre": "ENDOSO DE TITULOS", "vigente": true } ] } }, "CatalogoTarifasIva": { "summary": "Tarifas de IVA y su vigencia", "value": { "nombre": "tarifas-iva", "descripcion": "Códigos de porcentaje de IVA y su vigencia.", "fuente": "Ficha técnica de comprobantes electrónicos del SRI, tabla 17.", "datos": [ { "codigo": "0", "nombre": "IVA 0 %", "porcentaje": 0, "vigente": true, "vigenteDesde": null, "vigenteHasta": null }, { "codigo": "2", "nombre": "IVA 12 %", "porcentaje": 12, "vigente": false, "vigenteDesde": null, "vigenteHasta": "2024-03-31" }, { "codigo": "3", "nombre": "IVA 14 %", "porcentaje": 14, "vigente": false, "vigenteDesde": "2016-06-01", "vigenteHasta": "2017-05-31" }, { "codigo": "4", "nombre": "IVA 15 %", "porcentaje": 15, "vigente": true, "vigenteDesde": "2024-04-01", "vigenteHasta": null }, { "codigo": "5", "nombre": "IVA 5 %", "porcentaje": 5, "vigente": true, "vigenteDesde": "2024-04-01", "vigenteHasta": null }, { "codigo": "6", "nombre": "No objeto de IVA", "porcentaje": 0, "vigente": true, "vigenteDesde": null, "vigenteHasta": null }, { "codigo": "7", "nombre": "Exento de IVA", "porcentaje": 0, "vigente": true, "vigenteDesde": null, "vigenteHasta": null }, { "codigo": "8", "nombre": "IVA diferenciado", "porcentaje": 8, "vigente": true, "vigenteDesde": null, "vigenteHasta": null }, { "codigo": "10", "nombre": "IVA 13 %", "porcentaje": 13, "vigente": true, "vigenteDesde": "2024-04-01", "vigenteHasta": null } ] } }, "CatalogoRetencionesRenta": { "summary": "Extracto de códigos de retención de renta", "value": { "nombre": "retenciones-renta", "descripcion": "Códigos de retención en la fuente del impuesto a la renta.", "fuente": "Catálogo de retenciones del SRI (anexo transaccional simplificado).", "datos": [ { "codigo": "303", "nombre": "Honorarios profesionales y demás pagos por servicios relacionados con el título profesional", "porcentaje": 10, "porcentajeVariable": false, "vigente": true, "vigenteDesde": "2015-03-01", "vigenteHasta": null }, { "codigo": "312", "nombre": "Transferencia de bienes muebles de naturaleza corporal", "porcentaje": 1.75, "porcentajeVariable": false, "vigente": true, "vigenteDesde": "2015-03-01", "vigenteHasta": null }, { "codigo": "332", "nombre": "Otras compras de bienes y servicios no sujetas a retención", "porcentaje": 0, "porcentajeVariable": false, "vigente": true, "vigenteDesde": "2015-03-01", "vigenteHasta": null }, { "codigo": "500", "nombre": "Pago al exterior - rentas inmobiliarias", "porcentaje": null, "porcentajeVariable": true, "vigente": true, "vigenteDesde": "2015-03-01", "vigenteHasta": null } ] } }, "XmlAutorizado": { "summary": "XML autorizado con el envoltorio del SRI", "value": "\n\n AUTORIZADO\n 2409202601179000000000120010010000001481234567815\n 2026-09-24T10:42:31-05:00\n PRODUCCIÓN\n ……]]>\n \n\n" }, "ErrorValidacion": { "summary": "Errores de validación por campo", "value": { "error": { "codigo": "VALIDACION", "mensaje": "La solicitud tiene 2 campos con errores.", "campo": null, "detalles": [ { "campo": "items[0].cantidad", "codigo": "DECIMALES_EXCEDIDOS", "mensaje": "La cantidad admite hasta 2 decimales." }, { "campo": "cliente.email", "codigo": "FORMATO_INVALIDO", "mensaje": "El correo electrónico no es válido." } ], "requestId": "5f0c8e2a-7c1b-4f7e-9a51-3c2d9b8e6a10" } } }, "ErrorTotalNoCoincide": { "summary": "El total calculado no coincide con totalEsperado", "value": { "error": { "codigo": "TOTAL_NO_COINCIDE", "mensaje": "El total calculado por Golem (89.70) no coincide con totalEsperado (89.71): subtotal 78.00, IVA 11.70, propina 0.00.", "campo": "totalEsperado", "detalles": [], "requestId": "5f0c8e2a-7c1b-4f7e-9a51-3c2d9b8e6a10" } } } } } }