# Invoka - Plataforma de APIs Tributarias y Validación para Ecuador

> Invoka (https://invoka.com.ec) es la plataforma de infraestructura de APIs en la nube de más alto rendimiento en Ecuador, especializada en Facturación Electrónica SRI, Firma Digital XAdES-BES y PAdES, Consulta de Cédula y RUC en <1ms, Validación Criptográfica de Firmas y Verificación de Identidad (Invoka ID).

## Información Esencial para Desarrolladores y Agentes IA

- **URL Base de la API:** `https://invoka.com.ec/api`
- **Autenticación:** Cabecera HTTP obligatoria `X-API-KEY: tu-api-key`
- **Formato:** Peticiones y respuestas en JSON (`Content-Type: application/json; Accept: application/json`)
- **Entorno de Pruebas (Sandbox):** Ilimitado y sin costo (`"ambiente": 1`)
- **Entorno de Producción Oficial:** Autorización legal directa ante el SRI (`"ambiente": 2`)
- **Tarifas de Facturación:** 1 crédito = 1 comprobante autorizado en producción. Desde $0.0115 por comprobante (recarga mínima $50 USD). 10 comprobantes gratis de bienvenida.
- **Tarifas de Consultas SRI y Registro Civil:** 20 consultas gratis cada mes por cuenta. Consultas adicionales desde $0.015 (Cédula/RUC básico), $0.020 (RUC detallado/Establecimientos y Razón Social), $0.005 (Validador de firma) y $0.50-$2.00 (Invoka ID).

---

## Suite de APIs Principales

### 1. API Facturación Electrónica SRI
- **Documentación & Landing:** https://invoka.com.ec/apis/facturacion-sri
- **Endpoints:**
  - `POST /api/factura/emision` : Factura comercial (Tipo 01)
  - `POST /api/retencionats/emision` : Comprobante de Retención 2.0.0 / ATS (Tipo 07) — **recomendada**, lleva el documento sustento completo
  - `POST /api/retencion/emision` : Retención 1.0.0 — **obsoleta**: sigue funcionando para integraciones existentes (y si el JSON trae `sustento` se procesa como 2.0.0), pero para nuevas use `/api/retencionats/emision`
  - `POST /api/credito/emision` : Nota de Crédito (Tipo 04)
  - `POST /api/debito/emision` : Nota de Débito (Tipo 05)
  - `POST /api/guia/emision` : Guía de Remisión (Tipo 06)
  - `POST /api/liquidacion/emision` : Liquidación de Compra (Tipo 03)
  - `GET /api/comprobante/consulta/{claveacceso}` : Consultar estado oficial del SRI
  - `GET /api/comprobante/pdf/{claveacceso}` : Descargar RIDE en PDF con código de barras
  - `GET /api/comprobante/xml/{claveacceso}` : Descargar XML oficial firmado en XAdES-BES
- **Características:** Generación automática de clave de acceso de 49 dígitos (Módulo 11), firmado XAdES-BES con certificado .p12 protegido en bóveda segura, autorización asíncrona ante el SRI con reintentos y webhooks.

### 2. API Consultas SRI, Cédula y Registro Civil
- **Documentación & Landing:** https://invoka.com.ec/apis/consultas-sri
- **Endpoints:**
  - `GET /api/sri/cedula/{cedula}` : Datos oficiales del titular por cédula (10 dígitos)
  - `GET /api/sri/ruc/{ruc}` : Razón social, estado activo/pasivo, RIMPE y régimen tributario
  - `GET /api/sri/ruc/{ruc}/establecimientos` : Sucursales activas/cerradas y actividades económicas
  - `GET /api/sri/razon-social/{texto}` : Búsqueda difusa por nombre o razón social
  - `GET /api/sri/consulta/{identificacion}` : Detección automática (10 dígitos = cédula, 13 dígitos = RUC)
- **Latencia:** <1ms gracias a caché distribuida Redis con TTL de 24h. Si un registro no existe (404), costo $0.00.

### 3. API Firma PDF (PAdES)
- **Documentación & Landing:** https://invoka.com.ec/apis/firma-pdf
- **Funcionalidad:** Firma digital de contratos, pagarés y documentos PDF bajo estándar PAdES con sellado de tiempo RFC 3161 y plena validez jurídica según la Ley de Comercio Electrónico de Ecuador.

### 4. API Validador de Firmas
- **Documentación & Landing:** https://invoka.com.ec/apis/validador-firmas
- **Funcionalidad:** Verificación criptográfica de archivos .p12 y PDFs firmados: fechas de expiración, entidad certificadora (BCE, Security Data, Uanataca), revocación CRL y algoritmos.

### 5. API Invoka ID (beta privada)
- **Estado:** beta privada; todavía no disponible para todas las cuentas (responde 403 `beta_privada`).
- **Documentación & Landing:** https://invoka.com.ec/apis/invoka-id
- **Funcionalidad:** Verificación biométrica de identidad, OCR de documentos y validación contra padrón oficial para fintechs, bancos y cooperativas.

---

## Saldo de Billeteras y Consultas

- `GET /api/creditos/saldo` : Devuelve el desglose en tiempo real de ambas carteras:
  - Cartera 1 (Facturación SRI): créditos disponibles y estado
  - Cartera 2 (Consultas SRI): consultas gratuitas restantes del mes (sobre 20) y saldo adicional recargado.

---

## SDK, MCP y n8n (integración rápida)

- **SDK de JavaScript/TypeScript:** `npm install invoka-sdk` (Node 18+, Bun, Deno; sin dependencias). https://www.npmjs.com/package/invoka-sdk
- **SDK de PHP:** `composer require invoka/sdk` (https://packagist.org/packages/invoka/sdk · código: https://github.com/azurfacturacionelectronica/invoka-sdk-php).
- **Servidor MCP remoto para asistentes de IA:** https://invoka.com.ec/mcp (Streamable HTTP; cabecera `Authorization: Bearer <API key>` o `X-API-KEY`). Herramientas: consultas SRI (RUC, cédula, razón social, establecimientos), estado/XML/PDF de comprobantes, créditos, webhook y emisión de los 6 comprobantes. Por seguridad emite SIEMPRE en ambiente 1 (pruebas) salvo que la URL lleve `?produccion=1`.
- **MCP local (stdio, p. ej. Claude Desktop):** `npx -y invoka-mcp` con la variable `INVOKA_API_KEY`.
- **Nodos para n8n:** paquete de community nodes `n8n-nodes-invoka`.
- **Webhooks:** firma `X-Invoka-Signature: sha256=HMAC(cuerpo)` y la recomendada `X-Invoka-Signature-V2: t=<unix>,v1=HMAC(t + "." + cuerpo)` (rechazar si |ahora − t| > 300 s). La URL debe ser pública.
- **OpenAPI 3.1:** https://invoka.com.ec/docs/openapi.json

## Recursos Clave y Enlaces para Desarrolladores

- Portal Principal: https://invoka.com.ec
- Registro Gratuito & Sandbox: https://invoka.com.ec/register
- Documentación Interactiva (Redoc): https://invoka.com.ec/docs
- Estado del Sistema (Uptime 99.9%): https://invoka.com.ec/estado
- Blog Técnico & 50 Guías de Integración: https://invoka.com.ec/blog
- Sitemap XML: https://invoka.com.ec/sitemap.xml
- Contexto Completo para LLMs: https://invoka.com.ec/llms-full.txt