Facturas

Datos de una factura

Una factura necesita como mínimo:

• establecimiento y puntoEmision: los códigos de 3 dígitos del punto de emisión (GET /empresa los lista). Si los omites, se usa el punto por defecto del token.
• cliente: la identificación, la razón social y, para enviarle la factura, el correo.
• items: el código, la descripción, la cantidad, el precio unitario sin IVA y el IVA de cada ítem.
• formaPago (una forma por el total) o pagos (varias formas).

La tabla de la referencia lista todos los campos. Un campo que no está en ella se rechaza con 400 VALIDACION.

Cliente

• Identificación: cédula (10 dígitos), RUC (13 dígitos), pasaporte o identificación del exterior. Golem valida la cédula y el RUC.
• Tipo de identificación: si omites tipoIdentificacion, se deduce: 13 dígitos válidos → RUC (04), 10 dígitos válidos → cédula (05), 9999999999999 → consumidor final (07). Para pasaportes (06) y documentos del exterior (08) indícalo siempre.
• Identificación inválida: sin tipoIdentificacion, una cédula o un RUC que no son válidos no permiten deducir el tipo y la respuesta es 400 VALIDACION, con CAMPO_REQUERIDO en cliente.tipoIdentificacion. Con tipoIdentificacion 04 o 05, la respuesta es 422 IDENTIFICACION_INVALIDA en cliente.identificacion.
• Datos por comprobante: la razón social, la dirección y el correo de la solicitud se usan en esta factura. Golem no toma ni cambia los datos que otra empresa registró para la misma identificación.
• Correo: si omites email, se usa el último que tu empresa registró para ese cliente, si existe. En producción, cuando el SRI autoriza la factura, Golem envía al cliente el XML y el RIDE a ese correo.

Consumidor final

Para ventas sin identificar al comprador, envía "identificacion": "9999999999999". La razón social es opcional (se imprime CONSUMIDOR FINAL) y solo se usa el correo que venga en la solicitud.

El SRI limita el valor de una factura a consumidor final: por encima de USD 50.00 la solicitud responde 422 CONSUMIDOR_FINAL_EXCEDE_LIMITE y hay que identificar al comprador. Una factura a consumidor final no admite notas de crédito.

Ítems y productos

• codigo identifica el producto en el catálogo de tu empresa. Si ya existe, se usa ese producto y el catálogo no se modifica. Si no existe, se crea con el código, la descripción, el precio y el IVA de la solicitud (codigoAuxiliar y tipo solo se usan al crearlo; tipo es BIEN por defecto).
• descripcion es la que se imprime en el comprobante, aunque el producto del catálogo tenga otra.
• cantidad admite hasta 2 decimales y precioUnitario hasta 4. El precio va sin IVA.
• descuento es el valor en dólares de la línea completa, no un porcentaje, y no puede superar cantidad × precio (422 DESCUENTO_INVALIDO).
• Si el producto existe con control de inventario y no hay existencias suficientes, la factura no se emite: 422 SIN_STOCK. Los productos que crea el API no llevan control de inventario.

IVA de cada ítem

Indica el IVA con iva (porcentaje) o con codigoIva (código del SRI):

El porcentaje 0 siempre es la tarifa 0 %: para no objeto o exento usa codigoIva 6 o 7. Las tarifas de 12 % y 14 % ya no están vigentes y responden 422 TARIFA_IVA_NO_VIGENTE en una factura; solo se usan en notas de crédito de facturas de esas fechas. El catálogo tarifas-iva tiene la vigencia de cada código.

Cálculo de totales

Golem calcula la factura con el mismo método que la aplicación, redondeando la mitad hacia arriba:

1. Por ítem: cantidad × precio unitario, redondeado a 4 decimales; menos el descuento; redondeado a 2 decimales. Es el subtotal de la línea.
2. IVA de la línea: subtotal × tarifa / 100, redondeado a 2 decimales.
3. Por tarifa: la base es la suma de los subtotales y el IVA es la suma del IVA de sus líneas.
4. Total: suma de subtotales + suma de IVA + propina.

La respuesta trae el desglose en totales: subtotal, descuento, subtotalesIva (base y valor por tarifa), iva, propina y total.

Comparar con tu sistema

Si envías totalEsperado con el total que calculó tu sistema, Golem lo compara con el suyo: si difieren en más de 0.01, la factura no se emite y la respuesta 422 TOTAL_NO_COINCIDE muestra el desglose. Así detectas diferencias de cálculo antes de crear el comprobante.

Precios con IVA incluido

El API recibe el precio unitario sin IVA. Si tu sistema guarda el precio de venta con IVA (PVP), conviértelo:

precioUnitario = PVP ÷ (1 + tarifa / 100), redondeado a 4 decimales

Ejemplo con IVA 15 %: un PVP de 1.15 da un precio unitario de 1.0000; 3 unidades suman 3.00 + 0.45 de IVA = 3.45, lo mismo que se cobró.

Como el IVA se redondea por línea, el total puede diferir en 0.01 por línea de lo cobrado. Por ejemplo, un PVP de 1.03 da 0.8957; la línea queda en 0.90 + 0.14 de IVA = 1.04. Para esos casos:

• Envía en totalEsperado lo cobrado: una diferencia de 0.01 se acepta y una mayor se rechaza antes de emitir.
• Con pagos, la suma puede diferir del total en 0.01. Con formaPago, el pago es el total que calcula Golem.

La emisión con precios con IVA incluido está en la hoja de ruta.

Formas de pago

• formaPago: un código del catálogo formas-pago, por el total de la factura. Por ejemplo 01 (sin utilización del sistema financiero, efectivo) o 20 (otros con utilización del sistema financiero, como una transferencia).
• pagos: hasta 10 formas, cada una con su total y, si es a plazo, plazo y unidadTiempo (DIAS, MESES o ANIOS). Deben sumar el total de la factura con una diferencia de hasta 0.01; si no, 422 PAGOS_NO_CUADRAN.

Envía uno de los dos: si faltan ambos o vienen los dos, 400 VALIDACION.

Otros campos

• fechaEmision: por defecto hoy; se acepta hoy o ayer (hora de Ecuador). Ver Fecha de emisión desde 2026.
• referencia: identificador del documento en tu sistema, por ejemplo el número de pedido, hasta 100 caracteres. No se imprime y sirve para buscar la factura.
• propina: propina o cargo por servicio; se suma al total.
• guiaRemision: número de la guía de remisión con el formato 001-001-000000001.
• informacionAdicional: hasta 14 campos con nombre y valor que se imprimen en el RIDE. Golem agrega el campo obligatorio “RUC Proveedor”.

Después de emitir

La respuesta es 201 con el estado final o 202 si el SRI no respondió en 12 segundos (ver Estados). Cuando la factura está autorizada, descarga el XML y el RIDE. Para corregir una factura autorizada, emite una nota de crédito.

# Usa una clave nueva por cada comprobante en Idempotency-Key (por ejemplo, un UUID v4).
curl -X POST https://api.golem.ec/v1/comprobantes/facturas \
  --max-time 30 \
  -H "Authorization: Bearer $GOLEM_TOKEN" \
  -H "Idempotency-Key: f57ae464-4a05-49b1-bf73-e18ca8e85f8e" \
  -H "Content-Type: application/json" \
  -d '{
    "establecimiento": "001",
    "puntoEmision": "001",
    "cliente": {
      "identificacion": "0990000000001",
      "razonSocial": "CLIENTE DEMO S.A.",
      "email": "[email protected]"
    },
    "items": [
      {
        "codigo": "P-001",
        "descripcion": "Producto de ejemplo",
        "cantidad": 10,
        "precioUnitario": 7.8,
        "iva": 15
      }
    ],
    "formaPago": "20"
  }'

import { randomUUID } from 'node:crypto';

const respuesta = await fetch('https://api.golem.ec/v1/comprobantes/facturas', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.GOLEM_TOKEN}`,
    'Idempotency-Key': randomUUID(), // una clave nueva por cada comprobante; guárdala para repetir la solicitud si la conexión se corta
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    establecimiento: '001',
    puntoEmision: '001',
    cliente: {
      identificacion: '0990000000001',
      razonSocial: 'CLIENTE DEMO S.A.',
      email: '[email protected]',
    },
    items: [
      {
        codigo: 'P-001',
        descripcion: 'Producto de ejemplo',
        cantidad: 10,
        precioUnitario: 7.8,
        iva: 15,
      },
    ],
    formaPago: '20',
  }),
  signal: AbortSignal.timeout(30000),
});
const datos = await respuesta.json();
console.log(respuesta.status, datos);

import os
import uuid

import requests

respuesta = requests.post(
    "https://api.golem.ec/v1/comprobantes/facturas",
    headers={
        "Authorization": f"Bearer {os.environ['GOLEM_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),  # una clave nueva por cada comprobante; guárdala para repetir la solicitud si la conexión se corta
    },
    json={
        "establecimiento": "001",
        "puntoEmision": "001",
        "cliente": {
            "identificacion": "0990000000001",
            "razonSocial": "CLIENTE DEMO S.A.",
            "email": "[email protected]",
        },
        "items": [
            {
                "codigo": "P-001",
                "descripcion": "Producto de ejemplo",
                "cantidad": 10,
                "precioUnitario": 7.8,
                "iva": 15,
            },
        ],
        "formaPago": "20",
    },
    timeout=30,
)
print(respuesta.status_code, respuesta.json())

<?php
// composer require guzzlehttp/guzzle ramsey/uuid
require 'vendor/autoload.php';

use GuzzleHttp\Client;
use Ramsey\Uuid\Uuid;

$cliente = new Client(['base_uri' => 'https://api.golem.ec/v1/', 'timeout' => 30]);

$respuesta = $cliente->post('comprobantes/facturas', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('GOLEM_TOKEN'),
        'Idempotency-Key' => Uuid::uuid4()->toString(), // una clave nueva por cada comprobante; guárdala para repetir la solicitud si la conexión se corta
    ],
    'json' => [
        'establecimiento' => '001',
        'puntoEmision' => '001',
        'cliente' => [
            'identificacion' => '0990000000001',
            'razonSocial' => 'CLIENTE DEMO S.A.',
            'email' => '[email protected]',
        ],
        'items' => [
            [
                'codigo' => 'P-001',
                'descripcion' => 'Producto de ejemplo',
                'cantidad' => 10,
                'precioUnitario' => 7.8,
                'iva' => 15,
            ],
        ],
        'formaPago' => '20',
    ],
    'http_errors' => false,
]);

echo $respuesta->getStatusCode(), PHP_EOL, $respuesta->getBody(), PHP_EOL;

{
  "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": "[email protected]",
    "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"
  }
}

{
  "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": "[email protected]",
    "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
  }
}

{
  "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": "[email protected]",
    "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"
  }
}

{
  "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": "[email protected]",
    "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"
  }
}

{
  "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": "[email protected]",
    "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
  }
}

Más ejemplos de solicitud

Otros cuerpos válidos de la especificación: una factura con descuento, dos tarifas de IVA, dos pagos y referencia, y una factura a consumidor final.

{
  "establecimiento": "001",
  "puntoEmision": "001",
  "referencia": "PED-2026-00481",
  "cliente": {
    "tipoIdentificacion": "05",
    "identificacion": "1700000001",
    "razonSocial": "PERSONA DEMO",
    "email": "[email protected]",
    "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
}

{
  "cliente": {
    "identificacion": "9999999999999"
  },
  "items": [
    {
      "codigo": "CAFE-01",
      "descripcion": "Café de especialidad 250 g",
      "cantidad": 1,
      "precioUnitario": 8.5,
      "iva": 15
    }
  ],
  "formaPago": "01"
}