{"openapi":"3.0.0","info":{"title":"INVOKA API","description":"API de procesamiento de documentos electr\u00f3nicos para Ecuador. Sistema de facturaci\u00f3n electr\u00f3nica basado en cr\u00e9ditos para desarrolladores.\n\n## Proveedor SRI (Resoluci\u00f3n NAC-DGERCGC26-00000027)\n\n- **Producci\u00f3n (`ambiente` 2) requiere tus datos de proveedor aprobados.** Reg\u00edstralos en el panel, en *Proveedor SRI*: RUC con un establecimiento exclusivo con la actividad J62021002 o J62021003, m\u00e1s el certificado del RUC. Sin eso la API responde `creado: false`.\n- **`RUC Proveedor` lo agrega Invoka** en `infoAdicional` de todos los comprobantes cuando tus datos est\u00e1n aprobados. **No lo env\u00edes** en `informacion_adicional`: la API rechaza el comprobante.\n- **`informacion_adicional` admite m\u00e1ximo 14 campos** (el SRI acepta 15 y uno es el RUC Proveedor).\n- Mientras tus datos no est\u00e9n aprobados, cada respuesta trae el campo `aviso_proveedor_sri` con lo que falta.\n\n## Ejemplos de c\u00f3digo\n\nEsta documentaci\u00f3n incluye ejemplos de c\u00f3digo autom\u00e1ticos para cada endpoint en m\u00faltiples lenguajes:\n\n- **cURL** - Comandos de terminal listos para usar\n- **JavaScript** - Con fetch API nativo\n- **PHP** - Con cURL nativo\n- **Python** - Con requests library\n\nTodos los ejemplos incluyen el header `X-API-KEY` requerido para autenticaci\u00f3n.\n\n## Autenticaci\u00f3n y l\u00edmites\n\nCabecera `X-API-KEY` con la clave de tu cuenta (panel \u2192 Perfil). M\u00e1ximo 300 peticiones por minuto por API key (HTTP 429).\n\n## Webhooks firmados\n\nLos avisos de comprobantes llevan `X-Invoka-Signature: sha256=<HMAC-SHA256 hex del cuerpo crudo con tu secret>`. Detalle y c\u00f3digo de verificaci\u00f3n en la secci\u00f3n **Webhook**.\n\n## Asistentes de IA (MCP)\n\nServidor MCP remoto en `https:\/\/www.invoka.com.ec\/mcp` (Streamable HTTP; cabecera `Authorization: Bearer <tu API key>` o `X-API-KEY`). Por seguridad las herramientas que emiten usan siempre el ambiente 1 de pruebas, salvo que conectes `https:\/\/www.invoka.com.ec\/mcp?produccion=1`. Paquete local (stdio): `npx -y @invoka\/mcp` con la variable `INVOKA_API_KEY`.\n\nCada operaci\u00f3n tiene un `operationId` estable en snake_case para SDK, n8n y MCP.","version":"1.0.0","contact":{"name":"Soporte Invoka","email":"soporte@invoka.com.ec"}},"servers":[{"url":"https:\/\/www.invoka.com.ec","description":"API de Invoka"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY","description":"Clave API del usuario para autenticaci\u00f3n"}},"schemas":{"EmpresaCreate":{"type":"object","required":["ruc","razon_social"],"properties":{"ruc":{"type":"string","example":"1234567890001","description":"RUC de la empresa (13 d\u00edgitos)"},"razon_social":{"type":"string","example":"Empresa Demo S.A.","description":"Raz\u00f3n social de la empresa"},"ncontribuyenteespecial":{"type":"string","nullable":true,"example":"12345","description":"N\u00famero de contribuyente especial"},"calificacionartesanal":{"type":"string","nullable":true,"example":"ARTESANO","description":"Calificaci\u00f3n artesanal"},"exportador_habitual":{"type":"boolean","default":false,"description":"Exportador habitual"},"grancontribuyente":{"type":"boolean","default":false,"description":"Gran contribuyente"},"agenteretencion":{"type":"boolean","default":false,"description":"Agente de retenci\u00f3n. IMPORTANTE: Si es true, numero_resolucion es obligatorio"},"contabilidad":{"type":"boolean","default":false,"description":"Obligado a llevar contabilidad"},"regimen_rimpe":{"type":"boolean","default":false,"description":"R\u00e9gimen RIMPE. IMPORTANTE: Solo uno de los reg\u00edmenes puede estar activo"},"regimen_rimpe_popular":{"type":"boolean","default":false,"description":"R\u00e9gimen RIMPE Popular. IMPORTANTE: Solo uno de los reg\u00edmenes puede estar activo"},"numero_resolucion":{"type":"string","nullable":true,"example":"NAC-DGERCGC20-00000001","description":"N\u00famero de resoluci\u00f3n. OBLIGATORIO si agente_retencion = true"},"smtp":{"type":"boolean","default":false,"description":"Habilitar configuraci\u00f3n SMTP personalizada"},"smtp_host":{"type":"string","nullable":true,"example":"smtp.gmail.com","description":"Servidor SMTP. OBLIGATORIO si smtp = true"},"smtp_port":{"type":"integer","nullable":true,"example":587,"description":"Puerto SMTP. OBLIGATORIO si smtp = true"},"smtp_user":{"type":"string","nullable":true,"example":"noreply@empresa.com","description":"Usuario SMTP. OBLIGATORIO si smtp = true"},"smtp_password":{"type":"string","nullable":true,"example":"password123","description":"Contrase\u00f1a SMTP. OBLIGATORIO si smtp = true"},"smtp_encryption":{"type":"string","nullable":true,"enum":["tls","ssl",null],"example":"tls","description":"Tipo de encriptaci\u00f3n SMTP (tls, ssl o null)"},"smtp_from_email":{"type":"string","nullable":true,"example":"noreply@empresa.com","description":"Email remitente SMTP. OBLIGATORIO si smtp = true"},"smtp_from_name":{"type":"string","nullable":true,"example":"Empresa Demo S.A.","description":"Nombre del remitente SMTP"}}},"EmpresaResponse":{"type":"object","properties":{"respuesta":{"type":"boolean","example":true},"mensaje":{"type":"string","example":"Empresa creada exitosamente"},"data":{"type":"object","properties":{"id":{"type":"integer","example":1},"ruc":{"type":"string","example":"1234567890001"},"razon_social":{"type":"string","example":"Empresa Demo S.A."}}}}},"ErrorResponse":{"type":"object","properties":{"respuesta":{"type":"boolean","example":false},"errors":{"type":"object","example":{"ruc":["El campo RUC es obligatorio"]}}}}}},"tags":[{"name":"Autenticaci\u00f3n","description":"Todas las rutas `\/api\/...` (salvo `ping`, `status` y `public\/*`) piden la cabecera **`X-API-KEY`** con la clave de tu cuenta (panel \u2192 Perfil). L\u00edmite: **300 peticiones por minuto por API key** (HTTP 429 al pasarlo).\n\nLas respuestas de error traen `creado: false` (o `success: false`) y el motivo en `errors` \/ `error`. Ojo: los errores de validaci\u00f3n de los comprobantes responden **HTTP 200** con `creado: false`; revisa siempre ese campo."},{"name":"Empresas","description":"Alta y edici\u00f3n de los emisores (RUC) de tu cuenta, su firma electr\u00f3nica .p12 y su logo para el RIDE."},{"name":"Facturas","description":"La emisi\u00f3n es **as\u00edncrona**: la respuesta trae `creado` y la `claveacceso`; el estado final llega por webhook o con `GET \/api\/comprobante\/consulta\/{claveacceso}`. `ambiente` 1 = pruebas (gratis e ilimitado), 2 = producci\u00f3n (1 cr\u00e9dito por comprobante autorizado; requiere tus datos de proveedor SRI aprobados). `emisor.fecha_emision` debe ser la fecha de **hoy** en Ecuador (`AAAA\/MM\/DD`). Los errores de validaci\u00f3n responden HTTP 200 con `creado: false` y el detalle en `errors`.\n\nFactura (c\u00f3digo 01)."},{"name":"Notas de Cr\u00e9dito","description":"La emisi\u00f3n es **as\u00edncrona**: la respuesta trae `creado` y la `claveacceso`; el estado final llega por webhook o con `GET \/api\/comprobante\/consulta\/{claveacceso}`. `ambiente` 1 = pruebas (gratis e ilimitado), 2 = producci\u00f3n (1 cr\u00e9dito por comprobante autorizado; requiere tus datos de proveedor SRI aprobados). `emisor.fecha_emision` debe ser la fecha de **hoy** en Ecuador (`AAAA\/MM\/DD`). Los errores de validaci\u00f3n responden HTTP 200 con `creado: false` y el detalle en `errors`.\n\nNota de cr\u00e9dito (c\u00f3digo 04)."},{"name":"Notas de D\u00e9bito","description":"La emisi\u00f3n es **as\u00edncrona**: la respuesta trae `creado` y la `claveacceso`; el estado final llega por webhook o con `GET \/api\/comprobante\/consulta\/{claveacceso}`. `ambiente` 1 = pruebas (gratis e ilimitado), 2 = producci\u00f3n (1 cr\u00e9dito por comprobante autorizado; requiere tus datos de proveedor SRI aprobados). `emisor.fecha_emision` debe ser la fecha de **hoy** en Ecuador (`AAAA\/MM\/DD`). Los errores de validaci\u00f3n responden HTTP 200 con `creado: false` y el detalle en `errors`.\n\nNota de d\u00e9bito (c\u00f3digo 05)."},{"name":"Gu\u00edas de Remisi\u00f3n","description":"La emisi\u00f3n es **as\u00edncrona**: la respuesta trae `creado` y la `claveacceso`; el estado final llega por webhook o con `GET \/api\/comprobante\/consulta\/{claveacceso}`. `ambiente` 1 = pruebas (gratis e ilimitado), 2 = producci\u00f3n (1 cr\u00e9dito por comprobante autorizado; requiere tus datos de proveedor SRI aprobados). `emisor.fecha_emision` debe ser la fecha de **hoy** en Ecuador (`AAAA\/MM\/DD`). Los errores de validaci\u00f3n responden HTTP 200 con `creado: false` y el detalle en `errors`.\n\nGu\u00eda de remisi\u00f3n (c\u00f3digo 06)."},{"name":"Comprobantes de Retenci\u00f3n","description":"La emisi\u00f3n es **as\u00edncrona**: la respuesta trae `creado` y la `claveacceso`; el estado final llega por webhook o con `GET \/api\/comprobante\/consulta\/{claveacceso}`. `ambiente` 1 = pruebas (gratis e ilimitado), 2 = producci\u00f3n (1 cr\u00e9dito por comprobante autorizado; requiere tus datos de proveedor SRI aprobados). `emisor.fecha_emision` debe ser la fecha de **hoy** en Ecuador (`AAAA\/MM\/DD`). Los errores de validaci\u00f3n responden HTTP 200 con `creado: false` y el detalle en `errors`.\n\nComprobante de retenci\u00f3n (c\u00f3digo 07): versi\u00f3n 2.0.0 (ATS, recomendada) y 1.0.0."},{"name":"Liquidaciones de Compra","description":"La emisi\u00f3n es **as\u00edncrona**: la respuesta trae `creado` y la `claveacceso`; el estado final llega por webhook o con `GET \/api\/comprobante\/consulta\/{claveacceso}`. `ambiente` 1 = pruebas (gratis e ilimitado), 2 = producci\u00f3n (1 cr\u00e9dito por comprobante autorizado; requiere tus datos de proveedor SRI aprobados). `emisor.fecha_emision` debe ser la fecha de **hoy** en Ecuador (`AAAA\/MM\/DD`). Los errores de validaci\u00f3n responden HTTP 200 con `creado: false` y el detalle en `errors`.\n\nLiquidaci\u00f3n de compra (c\u00f3digo 03)."},{"name":"Consulta de Comprobantes","description":"Estado, XML autorizado, RIDE PDF y reproceso. Solo ves los comprobantes emitidos con tu API key."},{"name":"Procesamiento","description":"Ruta hist\u00f3rica para reactivar el procesamiento de un comprobante. Para integraciones nuevas usa `POST \/api\/comprobante\/reprocesar`."},{"name":"Webhook","description":"Invoka hace un **POST JSON** a tu URL cuando un comprobante llega a un estado definitivo:\n\n- `comprobante.autorizado`: el SRI lo autoriz\u00f3 (estado 4 o 9).\n- `comprobante.error`: termin\u00f3 con un error que hay que corregir (devuelto, no autorizado, firma inv\u00e1lida, establecimiento cerrado\u2026).\n\nAs\u00ed no necesitas consultar el estado en bucle. Un solo webhook por cuenta (sirve para todas tus empresas). Tambi\u00e9n acepta `PUT`.\n\n### Cabeceras de cada aviso\n\n| Cabecera | Valor |\n|---|---|\n| `Content-Type` | `application\/json` |\n| `User-Agent` | `Invoka-Webhook\/1.0` |\n| `X-Invoka-Event` | `comprobante.autorizado`, `comprobante.error` o `webhook.prueba` |\n| `X-Invoka-Delivery` | UUID del aviso: **el mismo en todos sus reintentos** (sirve para deduplicar) |\n| `X-Invoka-Signature` | `sha256=` + HMAC-SHA256 en hexadecimal (min\u00fasculas) del **cuerpo crudo** con tu `secret` |\n| `X-Invoka-Timestamp` | Momento del env\u00edo (segundos Unix) |\n| `X-Invoka-Signature-V2` | **Recomendada.** `t=<timestamp>,v1=<HMAC-SHA256 hex de \"<timestamp>.<cuerpo crudo>\" con tu secret>`. Rechaza el aviso si \\|ahora \u2212 t\\| > 300 s: as\u00ed nadie puede reenviarte un aviso viejo. |\n\nLa URL del webhook debe ser **p\u00fablica** (https recomendado): no se aceptan `localhost`, IP privadas ni direcciones internas. El `secret` completo solo se muestra al guardarlo; `GET \/api\/webhook` lo devuelve enmascarado.\n\n### C\u00f3mo verificar la firma\n\nCalcula el HMAC sobre los **bytes exactos** que recibes (no re-serialices el JSON: Invoka lo env\u00eda sin escapar `\/` ni caracteres Unicode) y comp\u00e1ralo en tiempo constante:\n\n```php\n$cuerpo = file_get_contents('php:\/\/input');\n$esperada = 'sha256=' . hash_hmac('sha256', $cuerpo, $secret);\nif (!hash_equals($esperada, $_SERVER['HTTP_X_INVOKA_SIGNATURE'] ?? '')) { http_response_code(401); exit; }\n```\n\n```js\n\/\/ Node \/ Express: app.post('\/invoka\/webhook', express.raw({ type: 'application\/json' }), ...)\nconst crypto = require('crypto');\nconst esperada = 'sha256=' + crypto.createHmac('sha256', secret).update(req.body).digest('hex');\nconst ok = crypto.timingSafeEqual(Buffer.from(esperada), Buffer.from(req.get('X-Invoka-Signature') || ''));\n```\n\n```python\nimport hmac, hashlib\nesperada = 'sha256=' + hmac.new(secret.encode(), request.get_data(), hashlib.sha256).hexdigest()\nok = hmac.compare_digest(esperada, request.headers.get('X-Invoka-Signature', ''))\n```\n\nLa firma no incluye marca de tiempo: si te preocupa la repetici\u00f3n de avisos, guarda `claveacceso` + `evento` y descarta duplicados.\n\n### Cuerpo\n\n`evento`, `claveacceso`, `tipo_comprobante`, `numero` (001-001-000000001), `ambiente`, `ruc_emisor`, `estado`, `estado_texto`, `autorizado`, `requiere_correccion`, `errores` (solo si hay error), `numero_autorizacion`, `fecha_autorizacion`, `xml` y `pdf` (URL de `\/api\/comprobante\/xml|pdf\/{claveacceso}`, que piden tu API key) y `enviado_en` (ISO 8601). Ver *Webhooks* al final de esta documentaci\u00f3n.\n\n### Reintentos\n\nResponde **2xx** en menos de 25 s. Si no, se reintenta: **5 intentos en total** (el primero y 4 reintentos a 1, 5, 15 y 60 minutos). Cada intento queda en `ultimas_entregas` de `GET \/api\/webhook`.\n\nSi no mandas `secret` se conserva el actual o se genera uno de 40 caracteres y se devuelve en la respuesta."},{"name":"Cr\u00e9ditos","description":"Saldo de la cartera de facturaci\u00f3n (1 cr\u00e9dito = 1 comprobante autorizado en producci\u00f3n; el ambiente 1 de pruebas es gratis) y de la cartera de consultas."},{"name":"Consultas SRI y Registro Civil","description":"Consultas en tiempo real al catastro del SRI y al Registro Civil. **20 consultas gratis al mes** por cuenta (se reinicia el d\u00eda 1); despu\u00e9s se descuentan de la billetera de consultas. Solo se cuenta\/cobra la consulta que devuelve datos (`success: true`). Resultados en cach\u00e9 24 h.\n\nCada ruta `\/api\/sri\/...` tiene el alias `\/api\/consulta\/...` y acepta tambi\u00e9n `POST` con el dato en el cuerpo JSON."},{"name":"Invoka ID","description":"**Beta privada: todav\u00eda no est\u00e1 disponible para todas las cuentas** (responde 403 `beta_privada`); escr\u00edbanos a soporte@invoka.com.ec si le interesa.\n\nVerificaci\u00f3n de identidad: OCR de c\u00e9dula, prueba de vida y cotejo facial. **Servicio con costo** (cartera general): `prueba_de_vida` $0.50, `cedula_ocr` $0.75, `completa` $1.00 (+ IVA) por verificaci\u00f3n."},{"name":"Estado y precios","description":"Rutas p\u00fablicas (sin API key): estado de los servicios y tabla de precios de cr\u00e9ditos."}],"paths":{"\/api\/empresa\/crear":{"post":{"tags":["Empresas"],"summary":"Crear nueva empresa","description":"Crear una nueva empresa en el sistema con campos de impuestos y SMTP opcionales. \n\n**REGLAS DE NEGOCIO IMPORTANTES:**\n\n**Impuestos:**\n- Solo un r\u00e9gimen puede estar activo (RIMPE o RIMPE Popular, no ambos)\n- Si agente_retencion=true, numero_resolucion es obligatorio\n- RUC debe tener 13 d\u00edgitos v\u00e1lidos\n\n**SMTP (Opcional):**\n- Si smtp=true, los siguientes campos son obligatorios: smtp_host, smtp_port, smtp_user, smtp_password, smtp_from_email\n- smtp_encryption puede ser: \"tls\", \"ssl\" o null\n- smtp_from_name es opcional incluso si smtp=true","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/EmpresaCreate"},"examples":{"empresa_basica":{"summary":"Empresa b\u00e1sica","description":"Ejemplo b\u00e1sico de creaci\u00f3n de empresa con solo campos obligatorios","value":{"ruc":"1234567890001","razon_social":"Empresa Demo S.A."}},"empresa_completa":{"summary":"Empresa completa con SMTP","description":"Ejemplo completo con campos de impuestos y configuraci\u00f3n SMTP","value":{"ruc":"1234567890001","razon_social":"Empresa Demo S.A.","ncontribuyenteespecial":"12345","grancontribuyente":true,"agenteretencion":true,"numero_resolucion":"NAC-DGERCGC20-00000001","contabilidad":true,"regimen_rimpe":true,"smtp":true,"smtp_host":"smtp.gmail.com","smtp_port":587,"smtp_user":"noreply@empresa.com","smtp_password":"password123","smtp_encryption":"tls","smtp_from_email":"noreply@empresa.com","smtp_from_name":"Empresa Demo S.A."}}}}}},"x-code-samples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https:\/\/www.invoka.com.ec\/api\/empresa\/crear\" \\\n  -H \"Content-Type: application\/json\" \\\n  -H \"X-API-KEY: tu-api-key-aqui\" \\\n  -d '{\n    \"ruc\": \"1234567890001\",\n    \"razon_social\": \"Empresa Demo S.A.\",\n    \"grancontribuyente\": true,\n    \"smtp\": true,\n    \"smtp_host\": \"smtp.gmail.com\",\n    \"smtp_port\": 587,\n    \"smtp_user\": \"noreply@empresa.com\",\n    \"smtp_password\": \"password123\",\n    \"smtp_encryption\": \"tls\",\n    \"smtp_from_email\": \"noreply@empresa.com\"\n  }'"},{"lang":"javascript","label":"JavaScript (fetch)","source":"fetch(\"https:\/\/www.invoka.com.ec\/api\/empresa\/crear\", {\n  method: \"POST\",\n  headers: {\n    \"Content-Type\": \"application\/json\",\n    \"X-API-KEY\": \"tu-api-key-aqui\"\n  },\n  body: JSON.stringify({\n    ruc: \"1234567890001\",\n    razon_social: \"Empresa Demo S.A.\",\n    grancontribuyente: true,\n    smtp: true,\n    smtp_host: \"smtp.gmail.com\",\n    smtp_port: 587,\n    smtp_user: \"noreply@empresa.com\",\n    smtp_password: \"password123\",\n    smtp_encryption: \"tls\",\n    smtp_from_email: \"noreply@empresa.com\"\n  })\n})\n.then(response => response.json())\n.then(data => console.log(data))\n.catch(error => console.error(\"Error:\", error));"},{"lang":"php","label":"PHP (cURL)","source":"<?php\n$curl = curl_init();\n\ncurl_setopt_array($curl, [\n  CURLOPT_URL => \"https:\/\/www.invoka.com.ec\/api\/empresa\/crear\",\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_CUSTOMREQUEST => \"POST\",\n  CURLOPT_POSTFIELDS => json_encode([\n    \"ruc\" => \"1234567890001\",\n    \"razon_social\" => \"Empresa Demo S.A.\",\n    \"grancontribuyente\" => true,\n    \"smtp\" => true,\n    \"smtp_host\" => \"smtp.gmail.com\",\n    \"smtp_port\" => 587,\n    \"smtp_user\" => \"noreply@empresa.com\",\n    \"smtp_password\" => \"password123\",\n    \"smtp_encryption\" => \"tls\",\n    \"smtp_from_email\" => \"noreply@empresa.com\"\n  ]),\n  CURLOPT_HTTPHEADER => [\n    \"Content-Type: application\/json\",\n    \"X-API-KEY: tu-api-key-aqui\"\n  ],\n]);\n\n$response = curl_exec($curl);\ncurl_close($curl);\n\n$data = json_decode($response, true);\nvar_dump($data);\n?>"},{"lang":"python","label":"Python (requests)","source":"import requests\nimport json\n\nurl = \"https:\/\/www.invoka.com.ec\/api\/empresa\/crear\"\nheaders = {\n    \"Content-Type\": \"application\/json\",\n    \"X-API-KEY\": \"tu-api-key-aqui\"\n}\n\npayload = {\n    \"ruc\": \"1234567890001\",\n    \"razon_social\": \"Empresa Demo S.A.\",\n    \"grancontribuyente\": True,\n    \"smtp\": True,\n    \"smtp_host\": \"smtp.gmail.com\",\n    \"smtp_port\": 587,\n    \"smtp_user\": \"noreply@empresa.com\",\n    \"smtp_password\": \"password123\",\n    \"smtp_encryption\": \"tls\",\n    \"smtp_from_email\": \"noreply@empresa.com\"\n}\n\nresponse = requests.post(url, headers=headers, json=payload)\nprint(response.json())"}],"responses":{"200":{"description":"Empresa creada exitosamente","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/EmpresaResponse"}}}},"400":{"description":"Error de validaci\u00f3n","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"}}}},"401":{"description":"API Key inv\u00e1lida","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"API Key inv\u00e1lida"}}}}}},"429":{"description":"M\u00e1s de 300 peticiones por minuto por API key"}},"operationId":"crear_empresa"}},"\/api\/empresa\/editar":{"put":{"tags":["Empresas"],"summary":"Editar empresa existente","description":"Actualizar datos de una empresa existente con campos de impuestos y SMTP opcionales. Se requiere RUC para identificar la empresa.\n\n**Aplican las mismas reglas de negocio que en crear empresa.**","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/EmpresaCreate"}}}},"x-code-samples":[{"lang":"curl","label":"cURL","source":"curl -X PUT \"https:\/\/www.invoka.com.ec\/api\/empresa\/editar\" \\\n  -H \"Content-Type: application\/json\" \\\n  -H \"X-API-KEY: tu-api-key-aqui\" \\\n  -d '{\n    \"ruc\": \"1234567890001\",\n    \"razon_social\": \"Empresa Demo S.A. (Actualizada)\",\n    \"smtp\": false\n  }'"},{"lang":"javascript","label":"JavaScript (fetch)","source":"fetch(\"https:\/\/www.invoka.com.ec\/api\/empresa\/editar\", {\n  method: \"PUT\",\n  headers: {\n    \"Content-Type\": \"application\/json\",\n    \"X-API-KEY\": \"tu-api-key-aqui\"\n  },\n  body: JSON.stringify({\n    ruc: \"1234567890001\",\n    razon_social: \"Empresa Demo S.A. (Actualizada)\",\n    smtp: false\n  })\n})\n.then(response => response.json())\n.then(data => console.log(data));"},{"lang":"php","label":"PHP (cURL)","source":"<?php\n$curl = curl_init();\n\ncurl_setopt_array($curl, [\n  CURLOPT_URL => \"https:\/\/www.invoka.com.ec\/api\/empresa\/editar\",\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_CUSTOMREQUEST => \"PUT\",\n  CURLOPT_POSTFIELDS => json_encode([\n    \"ruc\" => \"1234567890001\",\n    \"razon_social\" => \"Empresa Demo S.A. (Actualizada)\",\n    \"smtp\" => false\n  ]),\n  CURLOPT_HTTPHEADER => [\n    \"Content-Type: application\/json\",\n    \"X-API-KEY: tu-api-key-aqui\"\n  ],\n]);\n\n$response = curl_exec($curl);\ncurl_close($curl);\n\n$data = json_decode($response, true);\nvar_dump($data);\n?>"},{"lang":"python","label":"Python (requests)","source":"import requests\nimport json\n\nurl = \"https:\/\/www.invoka.com.ec\/api\/empresa\/editar\"\nheaders = {\n    \"Content-Type\": \"application\/json\",\n    \"X-API-KEY\": \"tu-api-key-aqui\"\n}\n\npayload = {\n    \"ruc\": \"1234567890001\",\n    \"razon_social\": \"Empresa Demo S.A. (Actualizada)\",\n    \"smtp\": False\n}\n\nresponse = requests.put(url, headers=headers, json=payload)\nprint(response.json())"}],"responses":{"200":{"description":"Empresa actualizada exitosamente","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/EmpresaResponse"}}}},"400":{"description":"Error de validaci\u00f3n","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"}}}},"404":{"description":"Empresa no encontrada"},"429":{"description":"M\u00e1s de 300 peticiones por minuto por API key"}},"operationId":"editar_empresa"}},"\/api\/empresa\/subirfirma":{"post":{"tags":["Empresas"],"summary":"Subir firma electr\u00f3nica","description":"Subir archivo de firma electr\u00f3nica (.p12) para una empresa. La firma se utiliza para firmar documentos electr\u00f3nicos.\n\n**M\u00c9TODOS DE ENV\u00cdO SOPORTADOS:**\n\n1. **Archivo multipart\/form-data** - Enviar como archivo adjunto\n2. **Base64 JSON** - Enviar el contenido codificado en base64\n\n**IMPORTANTE:** Solo se puede usar uno de los dos m\u00e9todos por request.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"multipart\/form-data":{"schema":{"type":"object","required":["ruc","firma_file","password"],"properties":{"ruc":{"type":"string","example":"1234567890001","description":"RUC de la empresa"},"firma_file":{"type":"string","format":"binary","description":"Archivo de firma electr\u00f3nica (.p12) - M\u00e1ximo 10MB"},"password":{"type":"string","example":"password123","description":"Contrase\u00f1a de la firma electr\u00f3nica"}}}},"application\/json":{"schema":{"type":"object","required":["ruc","firma_base64","password"],"properties":{"ruc":{"type":"string","example":"1234567890001","description":"RUC de la empresa"},"firma_base64":{"type":"string","example":"MIIKmQIBAzCCCl8GCSqGSIb3DQEHAaCCClAEggpMMIIKSDCCBH8GCSqGSIb...","description":"Contenido del archivo .p12 codificado en base64"},"password":{"type":"string","example":"password123","description":"Contrase\u00f1a de la firma electr\u00f3nica"}}}}}},"x-code-samples":[{"lang":"curl","label":"cURL (Archivo)","source":"curl -X POST \"https:\/\/www.invoka.com.ec\/api\/empresa\/subirfirma\" \\\n  -H \"X-API-KEY: tu-api-key-aqui\" \\\n  -F \"ruc=1234567890001\" \\\n  -F \"password=password123\" \\\n  -F \"firma_file=@\/ruta\/a\/tu\/firma.p12\""},{"lang":"curl","label":"cURL (Base64)","source":"curl -X POST \"https:\/\/www.invoka.com.ec\/api\/empresa\/subirfirma\" \\\n  -H \"Content-Type: application\/json\" \\\n  -H \"X-API-KEY: tu-api-key-aqui\" \\\n  -d '{\n    \"ruc\": \"1234567890001\",\n    \"password\": \"password123\",\n    \"firma_base64\": \"MIIKmQIBAzCCCl8GCSqGSIb3DQEHAaCCClAEggpMMIIKSDCCBH8GCSqGSIb...\"\n  }'"},{"lang":"javascript","label":"JavaScript (Archivo)","source":"const formData = new FormData();\nformData.append(\"ruc\", \"1234567890001\");\nformData.append(\"password\", \"password123\");\nformData.append(\"firma_file\", fileInput.files[0]); \/\/ input file element\n\nfetch(\"https:\/\/www.invoka.com.ec\/api\/empresa\/subirfirma\", {\n  method: \"POST\",\n  headers: {\n    \"X-API-KEY\": \"tu-api-key-aqui\"\n  },\n  body: formData\n})\n.then(response => response.json())\n.then(data => console.log(data));"},{"lang":"javascript","label":"JavaScript (Base64)","source":"\/\/ Convertir archivo a base64\nconst file = fileInput.files[0];\nconst reader = new FileReader();\nreader.onload = function() {\n  const base64 = reader.result.split(\",\")[1]; \/\/ remover \"data:application\/x-pkcs12;base64,\"\n  \n  fetch(\"https:\/\/www.invoka.com.ec\/api\/empresa\/subirfirma\", {\n    method: \"POST\",\n    headers: {\n      \"Content-Type\": \"application\/json\",\n      \"X-API-KEY\": \"tu-api-key-aqui\"\n    },\n    body: JSON.stringify({\n      ruc: \"1234567890001\",\n      password: \"password123\",\n      firma_base64: base64\n    })\n  })\n  .then(response => response.json())\n  .then(data => console.log(data));\n};\nreader.readAsDataURL(file);"},{"lang":"php","label":"PHP (Archivo)","source":"<?php\n$curl = curl_init();\n\ncurl_setopt_array($curl, [\n  CURLOPT_URL => \"https:\/\/www.invoka.com.ec\/api\/empresa\/subirfirma\",\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_POST => true,\n  CURLOPT_POSTFIELDS => [\n    \"ruc\" => \"1234567890001\",\n    \"password\" => \"password123\",\n    \"firma_file\" => curl_file_create(\"\/ruta\/a\/tu\/firma.p12\", \"application\/x-pkcs12\", \"firma.p12\")\n  ],\n  CURLOPT_HTTPHEADER => [\n    \"X-API-KEY: tu-api-key-aqui\"\n  ],\n]);\n\n$response = curl_exec($curl);\ncurl_close($curl);\n\n$data = json_decode($response, true);\nvar_dump($data);\n?>"},{"lang":"php","label":"PHP (Base64)","source":"<?php\n\/\/ Leer archivo y convertir a base64\n$firmaContent = file_get_contents(\"\/ruta\/a\/tu\/firma.p12\");\n$firmaBase64 = base64_encode($firmaContent);\n\n$curl = curl_init();\n\ncurl_setopt_array($curl, [\n  CURLOPT_URL => \"https:\/\/www.invoka.com.ec\/api\/empresa\/subirfirma\",\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_POST => true,\n  CURLOPT_POSTFIELDS => json_encode([\n    \"ruc\" => \"1234567890001\",\n    \"password\" => \"password123\",\n    \"firma_base64\" => $firmaBase64\n  ]),\n  CURLOPT_HTTPHEADER => [\n    \"Content-Type: application\/json\",\n    \"X-API-KEY: tu-api-key-aqui\"\n  ],\n]);\n\n$response = curl_exec($curl);\ncurl_close($curl);\n\n$data = json_decode($response, true);\nvar_dump($data);\n?>"},{"lang":"python","label":"Python (Archivo)","source":"import requests\n\nurl = \"https:\/\/www.invoka.com.ec\/api\/empresa\/subirfirma\"\nheaders = {\n    \"X-API-KEY\": \"tu-api-key-aqui\"\n}\n\nfiles = {\n    \"firma_file\": (\"firma.p12\", open(\"\/ruta\/a\/tu\/firma.p12\", \"rb\"), \"application\/x-pkcs12\")\n}\n\ndata = {\n    \"ruc\": \"1234567890001\",\n    \"password\": \"password123\"\n}\n\nresponse = requests.post(url, headers=headers, files=files, data=data)\nprint(response.json())"},{"lang":"python","label":"Python (Base64)","source":"import requests\nimport base64\n\n# Leer archivo y convertir a base64\nwith open(\"\/ruta\/a\/tu\/firma.p12\", \"rb\") as file:\n    firma_base64 = base64.b64encode(file.read()).decode(\"utf-8\")\n\nurl = \"https:\/\/www.invoka.com.ec\/api\/empresa\/subirfirma\"\nheaders = {\n    \"Content-Type\": \"application\/json\",\n    \"X-API-KEY\": \"tu-api-key-aqui\"\n}\n\npayload = {\n    \"ruc\": \"1234567890001\",\n    \"password\": \"password123\",\n    \"firma_base64\": firma_base64\n}\n\nresponse = requests.post(url, headers=headers, json=payload)\nprint(response.json())"}],"responses":{"200":{"description":"Firma subida exitosamente","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/EmpresaResponse"}}}},"400":{"description":"Error de validaci\u00f3n","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"}}}},"404":{"description":"Empresa no encontrada"},"429":{"description":"M\u00e1s de 300 peticiones por minuto por API key"}},"operationId":"subir_firma_electronica"}},"\/api\/empresa\/subirlogo":{"post":{"tags":["Empresas"],"summary":"Subir logo de empresa","description":"Subir imagen de logo para una empresa. El logo se utiliza en documentos electr\u00f3nicos generados.\n\n**M\u00c9TODOS DE ENV\u00cdO SOPORTADOS:**\n\n1. **Archivo multipart\/form-data** - Enviar como archivo adjunto\n2. **Base64 JSON** - Enviar el contenido codificado en base64\n\n**FORMATOS SOPORTADOS:** PNG, JPG, JPEG (m\u00e1ximo 2MB)\n\n**IMPORTANTE:** Solo se puede usar uno de los dos m\u00e9todos por request.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"multipart\/form-data":{"schema":{"type":"object","required":["ruc","logo_file"],"properties":{"ruc":{"type":"string","example":"1234567890001","description":"RUC de la empresa"},"logo_file":{"type":"string","format":"binary","description":"Archivo de imagen (PNG, JPG, JPEG) - M\u00e1ximo 2MB"}}}},"application\/json":{"schema":{"type":"object","required":["ruc","logo_base64"],"properties":{"ruc":{"type":"string","example":"1234567890001","description":"RUC de la empresa"},"logo_base64":{"type":"string","example":"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8\/5+hHgAHggJ\/PchI7wAAAABJRU5ErkJggg==","description":"Contenido de la imagen codificado en base64 (sin prefijo data:image\/...)"}}}}}},"x-code-samples":[{"lang":"curl","label":"cURL (Archivo)","source":"curl -X POST \"https:\/\/www.invoka.com.ec\/api\/empresa\/subirlogo\" \\\n  -H \"X-API-KEY: tu-api-key-aqui\" \\\n  -F \"ruc=1234567890001\" \\\n  -F \"logo_file=@\/ruta\/a\/tu\/logo.png\""},{"lang":"curl","label":"cURL (Base64)","source":"curl -X POST \"https:\/\/www.invoka.com.ec\/api\/empresa\/subirlogo\" \\\n  -H \"Content-Type: application\/json\" \\\n  -H \"X-API-KEY: tu-api-key-aqui\" \\\n  -d '{\n    \"ruc\": \"1234567890001\",\n    \"logo_base64\": \"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8\/5+hHgAHggJ\/PchI7wAAAABJRU5ErkJggg==\"\n  }'"},{"lang":"javascript","label":"JavaScript (Archivo)","source":"const formData = new FormData();\nformData.append(\"ruc\", \"1234567890001\");\nformData.append(\"logo_file\", fileInput.files[0]); \/\/ input file element\n\nfetch(\"https:\/\/www.invoka.com.ec\/api\/empresa\/subirlogo\", {\n  method: \"POST\",\n  headers: {\n    \"X-API-KEY\": \"tu-api-key-aqui\"\n  },\n  body: formData\n})\n.then(response => response.json())\n.then(data => console.log(data));"},{"lang":"javascript","label":"JavaScript (Base64)","source":"\/\/ Convertir archivo a base64\nconst file = fileInput.files[0];\nconst reader = new FileReader();\nreader.onload = function() {\n  const base64 = reader.result.split(\",\")[1]; \/\/ remover \"data:image\/...;base64,\"\n  \n  fetch(\"https:\/\/www.invoka.com.ec\/api\/empresa\/subirlogo\", {\n    method: \"POST\",\n    headers: {\n      \"Content-Type\": \"application\/json\",\n      \"X-API-KEY\": \"tu-api-key-aqui\"\n    },\n    body: JSON.stringify({\n      ruc: \"1234567890001\",\n      logo_base64: base64\n    })\n  })\n  .then(response => response.json())\n  .then(data => console.log(data));\n};\nreader.readAsDataURL(file);"},{"lang":"php","label":"PHP (Archivo)","source":"<?php\n$curl = curl_init();\n\ncurl_setopt_array($curl, [\n  CURLOPT_URL => \"https:\/\/www.invoka.com.ec\/api\/empresa\/subirlogo\",\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_POST => true,\n  CURLOPT_POSTFIELDS => [\n    \"ruc\" => \"1234567890001\",\n    \"logo_file\" => curl_file_create(\"\/ruta\/a\/tu\/logo.png\", \"image\/png\", \"logo.png\")\n  ],\n  CURLOPT_HTTPHEADER => [\n    \"X-API-KEY: tu-api-key-aqui\"\n  ],\n]);\n\n$response = curl_exec($curl);\ncurl_close($curl);\n\n$data = json_decode($response, true);\nvar_dump($data);\n?>"},{"lang":"php","label":"PHP (Base64)","source":"<?php\n\/\/ Leer imagen y convertir a base64\n$logoContent = file_get_contents(\"\/ruta\/a\/tu\/logo.png\");\n$logoBase64 = base64_encode($logoContent);\n\n$curl = curl_init();\n\ncurl_setopt_array($curl, [\n  CURLOPT_URL => \"https:\/\/www.invoka.com.ec\/api\/empresa\/subirlogo\",\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_POST => true,\n  CURLOPT_POSTFIELDS => json_encode([\n    \"ruc\" => \"1234567890001\",\n    \"logo_base64\" => $logoBase64\n  ]),\n  CURLOPT_HTTPHEADER => [\n    \"Content-Type: application\/json\",\n    \"X-API-KEY: tu-api-key-aqui\"\n  ],\n]);\n\n$response = curl_exec($curl);\ncurl_close($curl);\n\n$data = json_decode($response, true);\nvar_dump($data);\n?>"},{"lang":"python","label":"Python (Archivo)","source":"import requests\n\nurl = \"https:\/\/www.invoka.com.ec\/api\/empresa\/subirlogo\"\nheaders = {\n    \"X-API-KEY\": \"tu-api-key-aqui\"\n}\n\nfiles = {\n    \"logo_file\": (\"logo.png\", open(\"\/ruta\/a\/tu\/logo.png\", \"rb\"), \"image\/png\")\n}\n\ndata = {\n    \"ruc\": \"1234567890001\"\n}\n\nresponse = requests.post(url, headers=headers, files=files, data=data)\nprint(response.json())"},{"lang":"python","label":"Python (Base64)","source":"import requests\nimport base64\n\n# Leer imagen y convertir a base64\nwith open(\"\/ruta\/a\/tu\/logo.png\", \"rb\") as file:\n    logo_base64 = base64.b64encode(file.read()).decode(\"utf-8\")\n\nurl = \"https:\/\/www.invoka.com.ec\/api\/empresa\/subirlogo\"\nheaders = {\n    \"Content-Type\": \"application\/json\",\n    \"X-API-KEY\": \"tu-api-key-aqui\"\n}\n\npayload = {\n    \"ruc\": \"1234567890001\",\n    \"logo_base64\": logo_base64\n}\n\nresponse = requests.post(url, headers=headers, json=payload)\nprint(response.json())"}],"responses":{"200":{"description":"Logo subido exitosamente","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/EmpresaResponse"}}}},"400":{"description":"Error de validaci\u00f3n","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"}}}},"404":{"description":"Empresa no encontrada"},"429":{"description":"M\u00e1s de 300 peticiones por minuto por API key"}},"operationId":"subir_logo_empresa"}},"\/api\/ping":{"post":{"tags":["Autenticaci\u00f3n"],"summary":"Verificar conectividad","description":"Comprueba que la API responde. **No valida la API key** (responde `{\"pong\": true}` aunque no la env\u00edes): para comprobar que tu clave es v\u00e1lida usa `GET \/api\/creditos\/saldo`.","security":[],"x-code-samples":[{"lang":"curl","label":"cURL","source":"curl -X POST \"https:\/\/www.invoka.com.ec\/api\/ping\" \\\n  -H \"X-API-KEY: tu-api-key-aqui\""},{"lang":"javascript","label":"JavaScript (fetch)","source":"fetch(\"https:\/\/www.invoka.com.ec\/api\/ping\", {\n  method: \"POST\",\n  headers: {\n    \"X-API-KEY\": \"tu-api-key-aqui\"\n  }\n})\n.then(response => response.json())\n.then(data => console.log(data));"},{"lang":"php","label":"PHP (cURL)","source":"<?php\n$curl = curl_init();\n\ncurl_setopt_array($curl, [\n  CURLOPT_URL => \"https:\/\/www.invoka.com.ec\/api\/ping\",\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_POST => true,\n  CURLOPT_HTTPHEADER => [\n    \"X-API-KEY: tu-api-key-aqui\"\n  ],\n]);\n\n$response = curl_exec($curl);\ncurl_close($curl);\n\n$data = json_decode($response, true);\nvar_dump($data);\n?>"},{"lang":"python","label":"Python (requests)","source":"import requests\n\nurl = \"https:\/\/www.invoka.com.ec\/api\/ping\"\nheaders = {\n    \"X-API-KEY\": \"tu-api-key-aqui\"\n}\n\nresponse = requests.post(url, headers=headers)\nprint(response.json())"}],"responses":{"200":{"description":"La API est\u00e1 en l\u00ednea","content":{"application\/json":{"schema":{"type":"object","example":{"pong":true}}}}},"429":{"description":"M\u00e1s de 300 peticiones por minuto por API key"}},"operationId":"ping"}},"\/api\/factura\/emision":{"post":{"tags":["Facturas"],"summary":"Emitir factura electr\u00f3nica","description":"Crea y procesa una factura electr\u00f3nica (C\u00f3digo 01) seg\u00fan normativa SRI Ecuador.\n\n**IMPORTANTE:**\n- **Ambiente 1 (Pruebas)**: GRATIS e ilimitado - Para desarrollo y testing\n- **Ambiente 2 (Producci\u00f3n)**: Usa 1 cr\u00e9dito por factura autorizada\n- Los cr\u00e9ditos solo se descuentan cuando el SRI autoriza el comprobante\n- La factura debe cumplir con todas las validaciones del SRI Ecuador\n- **Formato de fecha**: YYYY\/MM\/DD (con barras, ejemplo: 2025\/07\/30)\n\n**ESTRUCTURA DE DATOS:**\n- **Emisor**: Datos de la empresa que emite (incluye secuencial y fecha de emisi\u00f3n)\n- **Comprador**: Datos del comprador\/cliente\n- **Items**: Array de productos\/servicios con sus impuestos\n- **Totales**: Se calculan autom\u00e1ticamente basados en items (opcional)\n- **Pagos**: Formas de pago utilizadas (opcional)\n- **Informaci\u00f3n adicional**: Campos personalizados (opcional)","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["emisor","ambiente","comprador","items"],"properties":{"emisor":{"type":"object","description":"Informaci\u00f3n del emisor\/empresa","required":["nombre_comercial","ruc","codigo_establecimiento","codigo_puntoemision","direccion_matriz","direccion_establecimiento","obligado_contabilidad","fecha_emision"],"properties":{"nombre_comercial":{"type":"string","maxLength":300,"example":"EMPRESA PRUEBA","description":"Nombre comercial del emisor"},"razon_social":{"type":"string","maxLength":300,"example":"MI EMPRESA SOCIEDAD ANONIMA","description":"Raz\u00f3n social del emisor (opcional)"},"ruc":{"type":"string","maxLength":13,"example":"1792345678001","description":"RUC del emisor (13 d\u00edgitos)"},"codigo_establecimiento":{"type":"string","maxLength":3,"example":"003","description":"C\u00f3digo de establecimiento (3 d\u00edgitos)"},"codigo_puntoemision":{"type":"string","maxLength":3,"example":"003","description":"C\u00f3digo de punto de emisi\u00f3n (3 d\u00edgitos)"},"direccion_matriz":{"type":"string","maxLength":300,"example":"QUITO - ECUADOR","description":"Direcci\u00f3n de la matriz"},"direccion_establecimiento":{"type":"string","maxLength":300,"example":"QUITO - ECUADOR","description":"Direcci\u00f3n del establecimiento"},"obligado_contabilidad":{"type":"string","enum":["SI","NO"],"example":"SI","description":"Obligado a llevar contabilidad (SI\/NO)"},"contribuyente_especial":{"type":"string","maxLength":50,"example":"5368","description":"N\u00famero de contribuyente especial (opcional)"},"calificacion_artesanal":{"type":"string","maxLength":50,"example":"","description":"Calificaci\u00f3n artesanal (opcional)"},"exportador_habitual":{"type":"boolean","example":false,"description":"Exportador habitual (opcional)"},"gran_contribuyente":{"type":"boolean","example":false,"description":"Gran contribuyente (opcional)"},"agente_retencion":{"type":"boolean","example":false,"description":"Agente de retenci\u00f3n (opcional)"},"contabilidad":{"type":"boolean","example":false,"description":"Contabilidad (opcional)"},"regimen_rimpe":{"type":"boolean","example":false,"description":"R\u00e9gimen RIMPE (opcional)"},"regimen_rimpe_popular":{"type":"boolean","example":false,"description":"R\u00e9gimen RIMPE Popular (opcional)"},"numero_resolucion":{"type":"string","maxLength":100,"example":"","description":"N\u00famero de resoluci\u00f3n (opcional)"},"secuencial":{"type":"string","maxLength":9,"example":"000002001","description":"N\u00famero secuencial del comprobante (opcional - se puede autogenerar)"},"fecha_emision":{"type":"string","example":"2025\/07\/30","description":"Fecha de emisi\u00f3n en formato YYYY\/MM\/DD (con barras)"}}},"ambiente":{"type":"integer","enum":[1,2],"example":1,"description":"Ambiente: 1=Pruebas (GRATIS), 2=Producci\u00f3n (usa cr\u00e9ditos)"},"tipo_emision":{"type":"integer","enum":[1,2],"example":1,"description":"Tipo de emisi\u00f3n: 1=Normal, 2=Contingencia (opcional, por defecto es 1)"},"comprador":{"type":"object","description":"Informaci\u00f3n del comprador\/cliente","required":["identificacion","tipo_identificacion","razon_social","direccion"],"properties":{"identificacion":{"type":"string","maxLength":20,"example":"9999999999999","description":"Identificaci\u00f3n del comprador"},"tipo_identificacion":{"type":"string","maxLength":2,"example":"07","description":"Tipo de identificaci\u00f3n del comprador (04=RUC, 05=C\u00e9dula, 06=Pasaporte, 07=Consumidor Final, etc.)"},"razon_social":{"type":"string","maxLength":300,"example":"CONSUMIDOR FINAL","description":"Raz\u00f3n social del comprador"},"direccion":{"type":"string","maxLength":300,"example":"QUITO","description":"Direcci\u00f3n del comprador"},"telefono":{"type":"string","maxLength":300,"example":"0987654321","description":"Tel\u00e9fono del comprador (opcional)"},"celular":{"type":"string","maxLength":300,"example":"0987654321","description":"Celular del comprador (opcional)"},"correo":{"type":"string","maxLength":300,"example":"cliente@ejemplo.com","description":"Email del comprador (opcional)"}}},"items":{"type":"array","description":"Detalle de productos\/servicios de la factura","minItems":1,"items":{"type":"object","required":["descripcion","precio_unitario","tipoproducto","cantidad","tipo_iva"],"properties":{"codigo_principal":{"type":"string","maxLength":25,"example":"PROD001","description":"C\u00f3digo principal del producto (opcional)"},"codigo_auxiliar":{"type":"string","maxLength":25,"example":"","description":"C\u00f3digo auxiliar (opcional)"},"descripcion":{"type":"string","maxLength":300,"example":"Producto de prueba","description":"Descripci\u00f3n del producto\/servicio"},"cantidad":{"type":"number","format":"float","example":1,"description":"Cantidad del producto"},"precio_unitario":{"type":"number","format":"float","example":10,"description":"Precio unitario sin impuestos"},"descuento":{"type":"number","format":"float","example":0,"description":"Descuento aplicado (opcional)"},"precio_total_sin_impuesto":{"type":"number","format":"float","example":10,"description":"Precio total sin impuesto (opcional - se calcula autom\u00e1ticamente)"},"tipoproducto":{"type":"integer","example":1,"description":"Tipo de producto (requerido)"},"tipo_iva":{"type":"integer","example":2,"description":"Tipo de IVA aplicado (0=Sin IVA, 2=IVA 12%, 3=IVA 14%, etc.)"},"tipo_ice":{"type":"integer","example":0,"description":"Tipo de ICE aplicado (opcional)"},"tipo_irbpnr":{"type":"integer","example":0,"description":"Tipo de IRBPNR aplicado (opcional)"},"subsidio":{"type":"number","format":"float","example":0,"description":"Subsidio aplicado (opcional)"},"unidad_medida":{"type":"integer","example":1,"description":"Unidad de medida (opcional)"},"detalles_adicionales":{"type":"array","description":"Detalles adicionales del producto (opcional)","items":{"type":"object","properties":{"nombre":{"type":"string","maxLength":300,"example":"Detalle","description":"Nombre del detalle adicional"},"detalle":{"type":"string","maxLength":300,"example":"Informaci\u00f3n adicional","description":"Valor del detalle adicional"}}}}}}},"totales":{"type":"array","description":"Totales de impuestos (opcional - se calcula autom\u00e1ticamente si no se env\u00eda)","items":{"type":"object","properties":{"codigo":{"type":"string","example":"2","description":"C\u00f3digo del impuesto (2=IVA, 3=ICE)"},"codigo_porcentaje":{"type":"string","example":"2","description":"C\u00f3digo del porcentaje"},"descuento_adicional":{"type":"number","format":"float","example":0,"description":"Descuento adicional"},"base_imponible":{"type":"number","format":"float","example":10,"description":"Base imponible"},"tarifa":{"type":"number","format":"float","example":12,"description":"Tarifa del impuesto"},"valor":{"type":"number","format":"float","example":1.2,"description":"Valor del impuesto"}}}},"pagos":{"type":"array","description":"Formas de pago (opcional)","items":{"type":"object","properties":{"tipo":{"type":"integer","example":20,"description":"Tipo de pago (20=Otros con utilizaci\u00f3n del sistema financiero)"},"total":{"type":"number","format":"float","example":11.2,"description":"Total del pago"},"tiempo":{"type":"string","example":"","description":"Tiempo de pago (opcional)"},"plazo":{"type":"integer","example":0,"description":"Plazo de pago (opcional)"}}}},"informacion_adicional":{"type":"array","description":"Informaci\u00f3n adicional (opcional)","items":{"type":"object","properties":{"nombre":{"type":"string","maxLength":300,"example":"Campo Adicional","description":"Nombre del campo adicional"},"detalle":{"type":"string","maxLength":300,"example":"Valor del campo","description":"Valor del campo adicional"}}}},"codigoDoc":{"type":"string","maxLength":300,"example":"01","description":"C\u00f3digo del documento (opcional)"},"guiaremision":{"type":"string","example":"","description":"Gu\u00eda de remisi\u00f3n (opcional)"},"placa":{"type":"string","example":"","description":"Placa del veh\u00edculo (opcional)"}}},"examples":{"factura_basica":{"summary":"Factura b\u00e1sica con IVA","description":"Ejemplo de factura simple con un producto gravado con IVA 12%","value":{"emisor":{"nombre_comercial":"EMPRESA PRUEBA","razon_social":"MI EMPRESA SOCIEDAD ANONIMA","ruc":"1792345678001","codigo_establecimiento":"003","codigo_puntoemision":"003","direccion_matriz":"QUITO - ECUADOR","direccion_establecimiento":"QUITO - ECUADOR","obligado_contabilidad":"SI","secuencial":"000002001","fecha_emision":"2025\/07\/30"},"ambiente":1,"comprador":{"identificacion":"9999999999999","tipo_identificacion":"07","razon_social":"CONSUMIDOR FINAL","direccion":"QUITO","correo":"cliente@ejemplo.com"},"items":[{"codigo_principal":"PROD001","descripcion":"Producto de prueba","cantidad":1,"precio_unitario":10,"descuento":0,"precio_total_sin_impuesto":10,"tipoproducto":1,"tipo_iva":2}]}},"factura_multiple_productos":{"summary":"Factura con m\u00faltiples productos","description":"Ejemplo de factura con varios productos y diferentes impuestos","value":{"emisor":{"nombre_comercial":"TechAdvanced","razon_social":"TECNOLOGIA AVANZADA SA","ruc":"0912345678001","codigo_establecimiento":"001","codigo_puntoemision":"002","direccion_matriz":"Av. Tecnol\u00f3gica 789, Quito, Ecuador","direccion_establecimiento":"Mall del Sur Local 45, Quito, Ecuador","obligado_contabilidad":"SI","contribuyente_especial":"5368","secuencial":"000000125","fecha_emision":"2025\/07\/25"},"ambiente":2,"comprador":{"identificacion":"0987654321001","tipo_identificacion":"04","razon_social":"EMPRESA COMPRADORA CIA LTDA","direccion":"Av. Comercial 321, Guayaquil, Ecuador","correo":"facturacion@compradora.com","telefono":"042-123456"},"items":[{"codigo_principal":"COMP001","codigo_auxiliar":"CPU-I7","descripcion":"Computadora Desktop Intel Core i7","cantidad":2,"precio_unitario":800,"descuento":50,"precio_total_sin_impuesto":1550,"tipoproducto":1,"tipo_iva":2},{"codigo_principal":"SOFT001","descripcion":"Licencia de software empresarial","cantidad":1,"precio_unitario":200,"descuento":0,"precio_total_sin_impuesto":200,"tipoproducto":1,"tipo_iva":0}]}}}}}},"x-code-samples":[{"lang":"curl","label":"cURL (Factura b\u00e1sica)","source":"curl -X POST \"https:\/\/www.invoka.com.ec\/api\/factura\/emision\" \\\n  -H \"Content-Type: application\/json\" \\\n  -H \"X-API-KEY: tu-api-key-aqui\" \\\n  -d '{\n    \"emisor\": {\n      \"nombre_comercial\": \"EMPRESA PRUEBA\",\n      \"razon_social\": \"MI EMPRESA SOCIEDAD ANONIMA\",\n      \"ruc\": \"1792345678001\",\n      \"codigo_establecimiento\": \"003\",\n      \"codigo_puntoemision\": \"003\",\n      \"direccion_matriz\": \"QUITO - ECUADOR\",\n      \"direccion_establecimiento\": \"QUITO - ECUADOR\",\n      \"obligado_contabilidad\": \"SI\",\n      \"secuencial\": \"000002001\",\n      \"fecha_emision\": \"2025\/07\/30\"\n    },\n    \"ambiente\": 1,\n    \"comprador\": {\n      \"identificacion\": \"9999999999999\",\n      \"tipo_identificacion\": \"07\",\n      \"razon_social\": \"CONSUMIDOR FINAL\",\n      \"direccion\": \"QUITO\",\n      \"correo\": \"cliente@ejemplo.com\"\n    },\n    \"items\": [\n      {\n        \"codigo_principal\": \"PROD001\",\n        \"descripcion\": \"Producto de prueba\",\n        \"cantidad\": 1.00,\n        \"precio_unitario\": 10.00,\n        \"descuento\": 0.00,\n        \"precio_total_sin_impuesto\": 10.00,\n        \"tipoproducto\": 1,\n        \"tipo_iva\": 2\n      }\n    ]\n  }'"},{"lang":"javascript","label":"JavaScript (fetch)","source":"const facturaData = {\n  emisor: {\n    nombre_comercial: \"EMPRESA PRUEBA\",\n    razon_social: \"MI EMPRESA SOCIEDAD ANONIMA\",\n    ruc: \"1792345678001\",\n    codigo_establecimiento: \"003\",\n    codigo_puntoemision: \"003\",\n    direccion_matriz: \"QUITO - ECUADOR\",\n    direccion_establecimiento: \"QUITO - ECUADOR\",\n    obligado_contabilidad: \"SI\",\n    secuencial: \"000002001\",\n    fecha_emision: \"2025\/07\/30\"\n  },\n  ambiente: 1, \/\/ 1=Pruebas (gratis), 2=Producci\u00f3n (usa cr\u00e9ditos)\n  comprador: {\n    identificacion: \"9999999999999\",\n    tipo_identificacion: \"07\",\n    razon_social: \"CONSUMIDOR FINAL\",\n    direccion: \"QUITO\",\n    correo: \"cliente@ejemplo.com\"\n  },\n  items: [\n    {\n      codigo_principal: \"PROD001\",\n      descripcion: \"Producto de prueba\",\n      cantidad: 1.00,\n      precio_unitario: 10.00,\n      descuento: 0.00,\n      precio_total_sin_impuesto: 10.00,\n      tipoproducto: 1,\n      tipo_iva: 2\n    }\n  ]\n};\n\nfetch(\"https:\/\/www.invoka.com.ec\/api\/factura\/emision\", {\n  method: \"POST\",\n  headers: {\n    \"Content-Type\": \"application\/json\",\n    \"X-API-KEY\": \"tu-api-key-aqui\"\n  },\n  body: JSON.stringify(facturaData)\n})\n.then(response => response.json())\n.then(data => {\n  if (data.creado) {\n    console.log(\"Factura creada:\", data.claveacceso);\n    console.log(\"ID Comprobante:\", data.id_comprobante);\n    console.log(\"Estado:\", data.estado);\n  } else {\n    console.error(\"Error:\", data.errors);\n  }\n})\n.catch(error => console.error(\"Error:\", error));"},{"lang":"php","label":"PHP (cURL)","source":"<?php\n$facturaData = [\n    \"emisor\" => [\n        \"nombre_comercial\" => \"EMPRESA PRUEBA\",\n        \"razon_social\" => \"MI EMPRESA SOCIEDAD ANONIMA\",\n        \"ruc\" => \"1792345678001\",\n        \"codigo_establecimiento\" => \"003\",\n        \"codigo_puntoemision\" => \"003\",\n        \"direccion_matriz\" => \"QUITO - ECUADOR\",\n        \"direccion_establecimiento\" => \"QUITO - ECUADOR\",\n        \"obligado_contabilidad\" => \"SI\",\n        \"secuencial\" => \"000002001\",\n        \"fecha_emision\" => \"2025\/07\/30\"\n    ],\n    \"ambiente\" => 1, \/\/ 1=Pruebas (gratis), 2=Producci\u00f3n (usa cr\u00e9ditos)\n    \"comprador\" => [\n        \"identificacion\" => \"9999999999999\",\n        \"tipo_identificacion\" => \"07\",\n        \"razon_social\" => \"CONSUMIDOR FINAL\",\n        \"direccion\" => \"QUITO\",\n        \"correo\" => \"cliente@ejemplo.com\"\n    ],\n    \"items\" => [\n        [\n            \"codigo_principal\" => \"PROD001\",\n            \"descripcion\" => \"Producto de prueba\",\n            \"cantidad\" => 1.00,\n            \"precio_unitario\" => 10.00,\n            \"descuento\" => 0.00,\n            \"precio_total_sin_impuesto\" => 10.00,\n            \"tipoproducto\" => 1,\n            \"tipo_iva\" => 2\n        ]\n    ]\n];\n\n$curl = curl_init();\n\ncurl_setopt_array($curl, [\n    CURLOPT_URL => \"https:\/\/www.invoka.com.ec\/api\/factura\/emision\",\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_POST => true,\n    CURLOPT_POSTFIELDS => json_encode($facturaData),\n    CURLOPT_HTTPHEADER => [\n        \"Content-Type: application\/json\",\n        \"X-API-KEY: tu-api-key-aqui\"\n    ],\n]);\n\n$response = curl_exec($curl);\n$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);\ncurl_close($curl);\n\n$data = json_decode($response, true);\n\nif ($httpCode == 200 && $data[\\\"creado\\\"]) {\n    echo \"Factura creada exitosamente:\\n\";\n    echo \"Clave de acceso: \" . $data[\\\"claveacceso\\\"] . \"\\n\";\n    echo \"ID Comprobante: \" . $data[\\\"id_comprobante\\\"] . \"\\n\";\n    echo \"Estado: \" . $data[\\\"estado\\\"] . \"\\n\";\n} else {\n    echo \"Error en la emisi\u00f3n:\\n\";\n    if (isset($data[\\\"errors\\\"])) {\n        print_r($data[\\\"errors\\\"]);\n    }\n}\n?>"},{"lang":"python","label":"Python (requests)","source":"import requests\nimport json\n\nfactura_data = {\n    \"emisor\": {\n        \"nombre_comercial\": \"EMPRESA PRUEBA\",\n        \"razon_social\": \"MI EMPRESA SOCIEDAD ANONIMA\",\n        \"ruc\": \"1792345678001\",\n        \"codigo_establecimiento\": \"003\",\n        \"codigo_puntoemision\": \"003\",\n        \"direccion_matriz\": \"QUITO - ECUADOR\",\n        \"direccion_establecimiento\": \"QUITO - ECUADOR\",\n        \"obligado_contabilidad\": \"SI\",\n        \"secuencial\": \"000002001\",\n        \"fecha_emision\": \"2025\/07\/30\"\n    },\n    \"ambiente\": 1,  # 1=Pruebas (gratis), 2=Producci\u00f3n (usa cr\u00e9ditos)\n    \"comprador\": {\n        \"identificacion\": \"9999999999999\",\n        \"tipo_identificacion\": \"07\",\n        \"razon_social\": \"CONSUMIDOR FINAL\",\n        \"direccion\": \"QUITO\",\n        \"correo\": \"cliente@ejemplo.com\"\n    },\n    \"items\": [\n        {\n            \"codigo_principal\": \"PROD001\",\n            \"descripcion\": \"Producto de prueba\",\n            \"cantidad\": 1.00,\n            \"precio_unitario\": 10.00,\n            \"descuento\": 0.00,\n            \"precio_total_sin_impuesto\": 10.00,\n            \"tipoproducto\": 1,\n            \"tipo_iva\": 2\n        }\n    ]\n}\n\nurl = \"https:\/\/www.invoka.com.ec\/api\/factura\/emision\"\nheaders = {\n    \"Content-Type\": \"application\/json\",\n    \"X-API-KEY\": \"tu-api-key-aqui\"\n}\n\ntry:\n    response = requests.post(url, headers=headers, json=factura_data)\n    response.raise_for_status()\n\n    data = response.json()\n\n    if data.get(\"creado\"):\n        print(f\"Factura creada exitosamente:\")\n        print(f\"Clave de acceso: {data[\\\"claveacceso\\\"]}\")\n        print(f\"ID Comprobante: {data[\\\"id_comprobante\\\"]}\")\n        print(f\"Estado: {data[\\\"estado\\\"]}\")\n    else:\n        print(f\"Error en la emisi\u00f3n:\")\n        if \\\"errors\\\" in data:\n            print(\"Detalles del error:\")\n            print(json.dumps(data[\\\"errors\\\"], indent=2))\n\nexcept requests.exceptions.RequestException as e:\n    print(f\"Error de conexi\u00f3n: {e}\")\nexcept json.JSONDecodeError as e:\n    print(f\"Error al decodificar respuesta: {e}\")"}],"responses":{"200":{"description":"Factura registrada exitosamente para procesamiento","content":{"application\/json":{"schema":{"type":"object","properties":{"creado":{"type":"boolean","example":true,"description":"Indica si la factura fue creada exitosamente"},"claveacceso":{"type":"string","example":"3007202501179234567800110020020000000001234567818","description":"Clave de acceso del comprobante generada"},"id_comprobante":{"type":"integer","example":123,"description":"ID interno del comprobante en la base de datos"},"estado":{"type":"string","example":"En procesamiento","description":"Estado actual del comprobante"},"mensaje":{"type":"string","example":"Factura registrada exitosamente. XML se generar\u00e1 de forma as\u00edncrona.","description":"Mensaje descriptivo del resultado"}}}}}},"400":{"description":"Error en los datos enviados","content":{"application\/json":{"schema":{"type":"object","properties":{"creado":{"type":"boolean","example":false},"errors":{"type":"array","description":"Lista de errores de validaci\u00f3n","items":{"type":"string"},"example":["El campo emisor.ruc es obligatorio.","El campo comprador.identificacion es obligatorio."]}}}}}},"401":{"description":"API Key inv\u00e1lida o no proporcionada","content":{"application\/json":{"schema":{"type":"object","properties":{"creado":{"type":"boolean","example":false},"errors":{"type":"array","items":{"type":"string"},"example":["API Key requerida en header X-API-KEY"]}}}}}},"409":{"description":"Clave de acceso duplicada","content":{"application\/json":{"schema":{"type":"object","properties":{"creado":{"type":"boolean","example":false},"claveacceso":{"type":"string","example":"3007202501179234567800110020020000000001234567818"},"errors":{"type":"array","items":{"type":"string"},"example":["Clave de Acceso ya existe para esta empresa"]}}}}}},"500":{"description":"Error interno del servidor","content":{"application\/json":{"schema":{"type":"object","properties":{"creado":{"type":"boolean","example":false},"claveacceso":{"type":"string","example":"3007202501179234567800110020020000000001234567818","description":"Clave de acceso generada"},"errors":{"type":"array","items":{"type":"string"},"example":["Error al registrar comprobante: Database connection failed"]}}}}}},"429":{"description":"M\u00e1s de 300 peticiones por minuto por API key"}},"operationId":"emitir_factura"}},"\/api\/credito\/emision":{"post":{"tags":["Notas de Cr\u00e9dito"],"summary":"Emitir nota de cr\u00e9dito electr\u00f3nica","description":"Crea y procesa una nota de cr\u00e9dito electr\u00f3nica (C\u00f3digo 04) seg\u00fan normativa SRI Ecuador.\n\n**IMPORTANTE:**\n- **Ambiente 1 (Pruebas)**: GRATIS e ilimitado - Para desarrollo y testing\n- **Ambiente 2 (Producci\u00f3n)**: Usa 1 cr\u00e9dito por nota de cr\u00e9dito autorizada\n- Las notas de cr\u00e9dito se usan para anular o modificar facturas previamente emitidas\n- Debe incluir la informaci\u00f3n del documento que modifica\n- **Formato de fecha**: YYYY\/MM\/DD (con barras, ejemplo: 2024\/01\/15). **La fecha de emisi\u00f3n debe ser la del d\u00eda** (hora de Ecuador): por normativa del SRI no se aceptan comprobantes con fecha anterior ni posterior.\n\n**ESTRUCTURA DE DATOS:**\n- **Emisor**: Datos de la empresa que emite (incluye secuencial y fecha de emisi\u00f3n)\n- **Comprador**: Datos del cliente al que se le emite la nota de cr\u00e9dito\n- **Documento modificado**: Informaci\u00f3n del comprobante que se est\u00e1 modificando\n- **Items**: Array de productos\/servicios con sus impuestos\n- **Informaci\u00f3n adicional**: Campos personalizados (opcional)","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["emisor","ambiente","comprador","items","documento_modificado"],"properties":{"emisor":{"type":"object","description":"Informaci\u00f3n del emisor\/empresa","required":["ruc","secuencial","fecha_emision","nombre_comercial","codigo_establecimiento","codigo_puntoemision","direccion_matriz","direccion_establecimiento"],"properties":{"ruc":{"type":"string","maxLength":13,"example":"0912345678001","description":"RUC del emisor (13 d\u00edgitos)"},"secuencial":{"type":"string","maxLength":9,"example":"000000001","description":"N\u00famero secuencial de la nota de cr\u00e9dito (9 d\u00edgitos)"},"fecha_emision":{"type":"string","example":"2024\/01\/15","description":"Fecha de emisi\u00f3n en formato YYYY\/MM\/DD (con barras)"},"nombre_comercial":{"type":"string","maxLength":300,"example":"Mi Empresa Comercial","description":"Nombre comercial del emisor"},"razon_social":{"type":"string","maxLength":300,"example":"MI EMPRESA S.A.","description":"Raz\u00f3n social del emisor (opcional)"},"codigo_establecimiento":{"type":"string","maxLength":3,"example":"001","description":"C\u00f3digo de establecimiento (3 d\u00edgitos)"},"codigo_puntoemision":{"type":"string","maxLength":3,"example":"001","description":"C\u00f3digo de punto de emisi\u00f3n (3 d\u00edgitos)"},"direccion_matriz":{"type":"string","maxLength":300,"example":"Av. Principal 123","description":"Direcci\u00f3n de la matriz"},"direccion_establecimiento":{"type":"string","maxLength":300,"example":"Av. Sucursal 456","description":"Direcci\u00f3n del establecimiento"},"obligado_contabilidad":{"type":"string","enum":["SI","NO"],"example":"SI","description":"Obligado a llevar contabilidad (opcional)"},"contribuyente_especial":{"type":"string","maxLength":50,"example":"12345","description":"N\u00famero de contribuyente especial (opcional)"},"agente_retencion":{"type":"boolean","example":false,"description":"Agente de retenci\u00f3n (opcional)"},"contribuyente_rimpe":{"type":"string","enum":["SI","NO"],"example":"NO","description":"Contribuyente RIMPE (opcional)"},"contribuyente_rimpe_popular":{"type":"string","enum":["SI","NO"],"example":"NO","description":"Contribuyente RIMPE Negocio Popular (opcional)"},"gran_contribuyente":{"type":"boolean","example":false,"description":"Gran contribuyente (opcional)"},"calificacion_artesanal":{"type":"string","maxLength":50,"example":"","description":"Calificaci\u00f3n artesanal (opcional)"},"regimen_rimpe":{"type":"boolean","example":false,"description":"R\u00e9gimen RIMPE (opcional)"},"regimen_rimpe_popular":{"type":"boolean","example":false,"description":"R\u00e9gimen RIMPE Popular (opcional)"},"numero_resolucion":{"type":"string","maxLength":100,"example":"","description":"N\u00famero de resoluci\u00f3n (opcional)"}}},"ambiente":{"type":"integer","enum":[1,2],"example":1,"description":"Ambiente: 1=Pruebas (GRATIS), 2=Producci\u00f3n (usa cr\u00e9ditos)"},"tipo_emision":{"type":"integer","enum":[1],"example":1,"description":"Tipo de emisi\u00f3n: 1=Normal (opcional, por defecto es 1)"},"comprador":{"type":"object","description":"Informaci\u00f3n del comprador\/cliente","required":["tipo_identificacion","identificacion","razon_social","direccion"],"properties":{"tipo_identificacion":{"type":"string","maxLength":2,"example":"05","description":"Tipo de identificaci\u00f3n (04=RUC, 05=C\u00e9dula, 06=Pasaporte, 07=Consumidor Final, 08=Identificaci\u00f3n del exterior)"},"identificacion":{"type":"string","maxLength":20,"example":"1234567890","description":"N\u00famero de identificaci\u00f3n del comprador"},"razon_social":{"type":"string","maxLength":300,"example":"Juan P\u00e9rez","description":"Nombre o raz\u00f3n social del comprador"},"direccion":{"type":"string","maxLength":300,"example":"Calle Secundaria 789","description":"Direcci\u00f3n del comprador"},"telefono":{"type":"string","maxLength":300,"example":"022345678","description":"Tel\u00e9fono del comprador (opcional)"},"celular":{"type":"string","maxLength":300,"example":"0987654321","description":"Celular del comprador (opcional)"},"correo":{"type":"string","maxLength":300,"example":"comprador@ejemplo.com","description":"Correo electr\u00f3nico del comprador (opcional)"}}},"documento_modificado":{"type":"object","description":"Informaci\u00f3n del documento que se est\u00e1 modificando","required":["codigo_documento_sustento","numero_documento_sustento","fecha_documento_sustento","motivo"],"properties":{"codigo_documento_sustento":{"type":"integer","example":1,"description":"C\u00f3digo del documento que se modifica (01=Factura, 04=Nota de Cr\u00e9dito, 05=Nota de D\u00e9bito, etc.)"},"numero_documento_sustento":{"type":"string","example":"001001000000001","description":"N\u00famero completo del documento que se modifica (sin guiones)"},"fecha_documento_sustento":{"type":"string","example":"2024\/01\/10","description":"Fecha del documento que se modifica en formato YYYY\/MM\/DD"},"motivo":{"type":"string","maxLength":300,"example":"Descuento por volumen","description":"Motivo de la nota de cr\u00e9dito"},"anula_comprobante":{"type":"string","example":"NO","description":"Indica si anula completamente el comprobante (opcional)"}}},"items":{"type":"array","description":"Detalle de productos\/servicios de la nota de cr\u00e9dito","minItems":1,"items":{"type":"object","required":["descripcion","cantidad","precio_unitario"],"properties":{"codigo_principal":{"type":"string","maxLength":25,"example":"PROD001","description":"C\u00f3digo principal del producto (opcional)"},"codigo_auxiliar":{"type":"string","maxLength":25,"example":"AUX001","description":"C\u00f3digo auxiliar del producto (opcional)"},"descripcion":{"type":"string","maxLength":300,"example":"Producto de ejemplo","description":"Descripci\u00f3n del producto\/servicio"},"cantidad":{"type":"number","format":"float","example":2,"description":"Cantidad del producto"},"precio_unitario":{"type":"number","format":"float","example":25,"description":"Precio unitario sin impuestos"},"descuento":{"type":"number","format":"float","example":5,"description":"Descuento aplicado (opcional)"},"tipoproducto":{"type":"integer","example":1,"description":"Tipo de producto (opcional)"},"tipo_iva":{"type":"integer","enum":[0,2,3,4,5,6,7,8,10],"example":2,"description":"Tipo de IVA (0=0%, 2=12%, 3=14%, 4=15%, 5=5%, 6=No objeto, 7=Exento, 8=8%, 10=13%) (opcional)"},"tipo_ice":{"type":"integer","example":0,"description":"Tipo de ICE (opcional)"},"valor_ice":{"type":"number","format":"float","example":0,"description":"Valor del ICE (opcional)"},"tipo_irbpnr":{"type":"integer","example":0,"description":"Tipo de IRBPNR (opcional)"},"subsidio":{"type":"number","format":"float","example":0,"description":"Subsidio aplicado (opcional)"},"unidad_medida":{"type":"integer","example":1,"description":"Unidad de medida (opcional)"},"detalles_adicionales":{"type":"array","description":"Detalles adicionales del producto (opcional)","items":{"type":"object","properties":{"nombre":{"type":"string","maxLength":300,"example":"Color","description":"Nombre del detalle"},"detalle":{"type":"string","maxLength":300,"example":"Azul","description":"Valor del detalle"}}}}}}},"informacion_adicional":{"type":"array","description":"Informaci\u00f3n adicional de la nota de cr\u00e9dito (opcional)","items":{"type":"object","properties":{"nombre":{"type":"string","maxLength":300,"example":"Observaciones","description":"Nombre del campo adicional"},"detalle":{"type":"string","maxLength":300,"example":"Nota de cr\u00e9dito por devoluci\u00f3n","description":"Detalle del campo adicional"}}}},"codigoDoc":{"type":"string","example":"04","description":"C\u00f3digo del documento (opcional, por defecto es 04 para notas de cr\u00e9dito)"}}},"examples":{"nota_credito_basica":{"summary":"Nota de cr\u00e9dito b\u00e1sica","description":"Ejemplo de nota de cr\u00e9dito simple modificando una factura","value":{"emisor":{"ruc":"0912345678001","secuencial":"000000001","fecha_emision":"2024\/01\/15","nombre_comercial":"Mi Empresa Comercial","razon_social":"MI EMPRESA S.A.","codigo_establecimiento":"001","codigo_puntoemision":"001","direccion_matriz":"Av. Principal 123","direccion_establecimiento":"Av. Sucursal 456","obligado_contabilidad":"SI"},"ambiente":1,"comprador":{"tipo_identificacion":"05","identificacion":"1234567890","razon_social":"Juan P\u00e9rez","direccion":"Calle Secundaria 789","correo":"comprador@ejemplo.com"},"documento_modificado":{"codigo_documento_sustento":1,"numero_documento_sustento":"001001000000001","fecha_documento_sustento":"2024\/01\/10","motivo":"Descuento por volumen"},"items":[{"codigo_principal":"PROD001","descripcion":"Producto de ejemplo","cantidad":2,"precio_unitario":25,"descuento":5,"tipo_iva":2}]}}}}}},"x-code-samples":[{"lang":"curl","label":"cURL (Nota de cr\u00e9dito b\u00e1sica)","source":"curl -X POST \"https:\/\/www.invoka.com.ec\/api\/credito\/emision\" \\\n  -H \"Content-Type: application\/json\" \\\n  -H \"X-API-KEY: tu-api-key-aqui\" \\\n  -d '{\n    \"emisor\": {\n      \"ruc\": \"0912345678001\",\n      \"secuencial\": \"000000001\",\n      \"fecha_emision\": \"2024\/01\/15\",\n      \"nombre_comercial\": \"Mi Empresa Comercial\",\n      \"razon_social\": \"MI EMPRESA S.A.\",\n      \"codigo_establecimiento\": \"001\",\n      \"codigo_puntoemision\": \"001\",\n      \"direccion_matriz\": \"Av. Principal 123\",\n      \"direccion_establecimiento\": \"Av. Sucursal 456\",\n      \"obligado_contabilidad\": \"SI\"\n    },\n    \"ambiente\": 1,\n    \"comprador\": {\n      \"tipo_identificacion\": \"05\",\n      \"identificacion\": \"1234567890\",\n      \"razon_social\": \"Juan P\u00e9rez\",\n      \"direccion\": \"Calle Secundaria 789\",\n      \"correo\": \"comprador@ejemplo.com\"\n    },\n    \"documento_modificado\": {\n      \"codigo_documento_sustento\": 1,\n      \"numero_documento_sustento\": \"001001000000001\",\n      \"fecha_documento_sustento\": \"2024\/01\/10\",\n      \"motivo\": \"Descuento por volumen\"\n    },\n    \"items\": [\n      {\n        \"codigo_principal\": \"PROD001\",\n        \"descripcion\": \"Producto de ejemplo\",\n        \"cantidad\": 2.00,\n        \"precio_unitario\": 25.00,\n        \"descuento\": 5.00,\n        \"tipo_iva\": 2\n      }\n    ]\n  }'"},{"lang":"javascript","label":"JavaScript (fetch)","source":"const notaCreditoData = {\n  emisor: {\n    ruc: \"0912345678001\",\n    secuencial: \"000000001\",\n    fecha_emision: \"2024\/01\/15\",\n    nombre_comercial: \"Mi Empresa Comercial\",\n    razon_social: \"MI EMPRESA S.A.\",\n    codigo_establecimiento: \"001\",\n    codigo_puntoemision: \"001\",\n    direccion_matriz: \"Av. Principal 123\",\n    direccion_establecimiento: \"Av. Sucursal 456\",\n    obligado_contabilidad: \"SI\"\n  },\n  ambiente: 1, \/\/ 1=Pruebas (gratis), 2=Producci\u00f3n (usa cr\u00e9ditos)\n  comprador: {\n    tipo_identificacion: \"05\",\n    identificacion: \"1234567890\",\n    razon_social: \"Juan P\u00e9rez\",\n    direccion: \"Calle Secundaria 789\",\n    correo: \"comprador@ejemplo.com\"\n  },\n  documento_modificado: {\n    codigo_documento_sustento: 1,\n    numero_documento_sustento: \"001001000000001\",\n    fecha_documento_sustento: \"2024\/01\/10\",\n    motivo: \"Descuento por volumen\"\n  },\n  items: [\n    {\n      codigo_principal: \"PROD001\",\n      descripcion: \"Producto de ejemplo\",\n      cantidad: 2.00,\n      precio_unitario: 25.00,\n      descuento: 5.00,\n      tipo_iva: 2\n    }\n  ]\n};\n\nfetch(\"https:\/\/www.invoka.com.ec\/api\/credito\/emision\", {\n  method: \"POST\",\n  headers: {\n    \"Content-Type\": \"application\/json\",\n    \"X-API-KEY\": \"tu-api-key-aqui\"\n  },\n  body: JSON.stringify(notaCreditoData)\n})\n.then(response => response.json())\n.then(data => {\n  if (data.creado) {\n    console.log(\"Nota de cr\u00e9dito creada:\", data.claveacceso);\n    console.log(\"ID Comprobante:\", data.id_comprobante);\n  } else {\n    console.error(\"Error:\", data.errors);\n  }\n})\n.catch(error => console.error(\"Error:\", error));"},{"lang":"php","label":"PHP (cURL)","source":"<?php\n$notaCreditoData = [\n    \"emisor\" => [\n        \"ruc\" => \"0912345678001\",\n        \"secuencial\" => \"000000001\",\n        \"fecha_emision\" => \"2024\/01\/15\",\n        \"nombre_comercial\" => \"Mi Empresa Comercial\",\n        \"razon_social\" => \"MI EMPRESA S.A.\",\n        \"codigo_establecimiento\" => \"001\",\n        \"codigo_puntoemision\" => \"001\",\n        \"direccion_matriz\" => \"Av. Principal 123\",\n        \"direccion_establecimiento\" => \"Av. Sucursal 456\",\n        \"obligado_contabilidad\" => \"SI\"\n    ],\n    \"ambiente\" => 1, \/\/ 1=Pruebas (gratis), 2=Producci\u00f3n (usa cr\u00e9ditos)\n    \"comprador\" => [\n        \"tipo_identificacion\" => \"05\",\n        \"identificacion\" => \"1234567890\",\n        \"razon_social\" => \"Juan P\u00e9rez\",\n        \"direccion\" => \"Calle Secundaria 789\",\n        \"correo\" => \"comprador@ejemplo.com\"\n    ],\n    \"documento_modificado\" => [\n        \"codigo_documento_sustento\" => 1,\n        \"numero_documento_sustento\" => \"001001000000001\",\n        \"fecha_documento_sustento\" => \"2024\/01\/10\",\n        \"motivo\" => \"Descuento por volumen\"\n    ],\n    \"items\" => [\n        [\n            \"codigo_principal\" => \"PROD001\",\n            \"descripcion\" => \"Producto de ejemplo\",\n            \"cantidad\" => 2.00,\n            \"precio_unitario\" => 25.00,\n            \"descuento\" => 5.00,\n            \"tipo_iva\" => 2\n        ]\n    ]\n];\n\n$curl = curl_init();\n\ncurl_setopt_array($curl, [\n    CURLOPT_URL => \"https:\/\/www.invoka.com.ec\/api\/credito\/emision\",\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_POST => true,\n    CURLOPT_POSTFIELDS => json_encode($notaCreditoData),\n    CURLOPT_HTTPHEADER => [\n        \"Content-Type: application\/json\",\n        \"X-API-KEY: tu-api-key-aqui\"\n    ],\n]);\n\n$response = curl_exec($curl);\n$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);\ncurl_close($curl);\n\n$data = json_decode($response, true);\n\nif ($httpCode == 200 && $data[\\\"creado\\\"]) {\n    echo \"Nota de cr\u00e9dito creada exitosamente:\\n\";\n    echo \"Clave de acceso: \" . $data[\\\"claveacceso\\\"] . \"\\n\";\n    echo \"ID Comprobante: \" . $data[\\\"id_comprobante\\\"] . \"\\n\";\n} else {\n    echo \"Error en la emisi\u00f3n:\\n\";\n    if (isset($data[\\\"errors\\\"])) {\n        print_r($data[\\\"errors\\\"]);\n    }\n}\n?>"},{"lang":"python","label":"Python (requests)","source":"import requests\nimport json\n\nnota_credito_data = {\n    \"emisor\": {\n        \"ruc\": \"0912345678001\",\n        \"secuencial\": \"000000001\",\n        \"fecha_emision\": \"2024\/01\/15\",\n        \"nombre_comercial\": \"Mi Empresa Comercial\",\n        \"razon_social\": \"MI EMPRESA S.A.\",\n        \"codigo_establecimiento\": \"001\",\n        \"codigo_puntoemision\": \"001\",\n        \"direccion_matriz\": \"Av. Principal 123\",\n        \"direccion_establecimiento\": \"Av. Sucursal 456\",\n        \"obligado_contabilidad\": \"SI\"\n    },\n    \"ambiente\": 1,  # 1=Pruebas (gratis), 2=Producci\u00f3n (usa cr\u00e9ditos)\n    \"comprador\": {\n        \"tipo_identificacion\": \"05\",\n        \"identificacion\": \"1234567890\",\n        \"razon_social\": \"Juan P\u00e9rez\",\n        \"direccion\": \"Calle Secundaria 789\",\n        \"correo\": \"comprador@ejemplo.com\"\n    },\n    \"documento_modificado\": {\n        \"codigo_documento_sustento\": 1,\n        \"numero_documento_sustento\": \"001001000000001\",\n        \"fecha_documento_sustento\": \"2024\/01\/10\",\n        \"motivo\": \"Descuento por volumen\"\n    },\n    \"items\": [\n        {\n            \"codigo_principal\": \"PROD001\",\n            \"descripcion\": \"Producto de ejemplo\",\n            \"cantidad\": 2.00,\n            \"precio_unitario\": 25.00,\n            \"descuento\": 5.00,\n            \"tipo_iva\": 2\n        }\n    ]\n}\n\nurl = \"https:\/\/www.invoka.com.ec\/api\/credito\/emision\"\nheaders = {\n    \"Content-Type\": \"application\/json\",\n    \"X-API-KEY\": \"tu-api-key-aqui\"\n}\n\ntry:\n    response = requests.post(url, headers=headers, json=nota_credito_data)\n    response.raise_for_status()\n\n    data = response.json()\n\n    if data.get(\"creado\"):\n        print(f\"Nota de cr\u00e9dito creada exitosamente:\")\n        print(f\"Clave de acceso: {data[\\\"claveacceso\\\"]}\")\n        print(f\"ID Comprobante: {data[\\\"id_comprobante\\\"]}\")\n    else:\n        print(f\"Error en la emisi\u00f3n:\")\n        if \\\"errors\\\" in data:\n            print(\"Detalles del error:\")\n            print(json.dumps(data[\\\"errors\\\"], indent=2))\n\nexcept requests.exceptions.RequestException as e:\n    print(f\"Error de conexi\u00f3n: {e}\")\nexcept json.JSONDecodeError as e:\n    print(f\"Error al decodificar respuesta: {e}\")"}],"responses":{"200":{"description":"Nota de cr\u00e9dito registrada exitosamente para procesamiento","content":{"application\/json":{"schema":{"type":"object","properties":{"creado":{"type":"boolean","example":true,"description":"Indica si la nota de cr\u00e9dito fue creada exitosamente"},"claveacceso":{"type":"string","example":"1501202404091234567800110010010000000011234567890","description":"Clave de acceso del comprobante generada"},"id_comprobante":{"type":"integer","example":12345,"description":"ID interno del comprobante en la base de datos"}}}}}},"400":{"description":"Error en los datos enviados","content":{"application\/json":{"schema":{"type":"object","properties":{"creado":{"type":"boolean","example":false},"errors":{"type":"array","description":"Lista de errores de validaci\u00f3n","items":{"type":"string"},"example":["El campo emisor.ruc es obligatorio.","El campo documento_modificado.motivo es obligatorio."]}}}}}},"401":{"description":"API Key inv\u00e1lida o empresa no existe","content":{"application\/json":{"schema":{"type":"object","properties":{"creado":{"type":"boolean","example":false},"errors":{"type":"array","items":{"type":"string"},"example":["Api_key No existe"]}}}}}},"500":{"description":"Error interno del servidor","content":{"application\/json":{"schema":{"type":"object","properties":{"respuesta":{"type":"boolean","example":false},"error":{"type":"string","example":"Error interno del servidor"}}}}}},"429":{"description":"M\u00e1s de 300 peticiones por minuto por API key"}},"operationId":"emitir_nota_credito"}},"\/api\/guia\/emision":{"post":{"tags":["Gu\u00edas de Remisi\u00f3n"],"summary":"Emitir gu\u00eda de remisi\u00f3n electr\u00f3nica","description":"Crea y procesa una gu\u00eda de remisi\u00f3n electr\u00f3nica (C\u00f3digo 06) seg\u00fan normativa SRI Ecuador.\n\n**IMPORTANTE:**\n- **Ambiente 1 (Pruebas)**: GRATIS e ilimitado - Para desarrollo y testing\n- **Ambiente 2 (Producci\u00f3n)**: Usa 1 cr\u00e9dito por gu\u00eda de remisi\u00f3n autorizada\n- Las gu\u00edas de remisi\u00f3n se usan para documentar el traslado de mercanc\u00edas\n- Debe incluir informaci\u00f3n del transportista, destinatario y detalles del traslado\n- **Formato de fecha**: YYYY\/MM\/DD (con barras, ejemplo: 2024\/01\/15). **La fecha de emisi\u00f3n debe ser la del d\u00eda** (hora de Ecuador): por normativa del SRI no se aceptan comprobantes con fecha anterior ni posterior.\n\n**ESTRUCTURA DE DATOS:**\n- **Emisor**: Datos de la empresa que emite (incluye secuencial y fecha de emisi\u00f3n)\n- **Transportista**: Datos de quien transporta las mercanc\u00edas\n- **Destinatario**: Datos de quien recibe las mercanc\u00edas\n- **Traslado**: Informaci\u00f3n del transporte (fechas, origen, destino, ruta, motivo)\n- **Items**: Array de productos\/mercanc\u00edas a transportar\n- **Documento sustento**: Documento que respalda el traslado (opcional)\n- **Informaci\u00f3n adicional**: Campos personalizados (opcional)","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["emisor","ambiente","transportista","destinatario","traslado","items"],"properties":{"emisor":{"type":"object","description":"Informaci\u00f3n del emisor\/empresa","required":["ruc","secuencial","fecha_emision","nombre_comercial","codigo_establecimiento","codigo_puntoemision","direccion_matriz","direccion_establecimiento"],"properties":{"ruc":{"type":"string","maxLength":13,"example":"0912345678001","description":"RUC del emisor (13 d\u00edgitos)"},"secuencial":{"type":"string","maxLength":9,"example":"000000001","description":"N\u00famero secuencial de la gu\u00eda de remisi\u00f3n (9 d\u00edgitos)"},"fecha_emision":{"type":"string","example":"2024\/01\/15","description":"Fecha de emisi\u00f3n en formato YYYY\/MM\/DD (con barras)"},"nombre_comercial":{"type":"string","maxLength":300,"example":"Mi Empresa Comercial","description":"Nombre comercial del emisor"},"razon_social":{"type":"string","maxLength":300,"example":"MI EMPRESA S.A.","description":"Raz\u00f3n social del emisor (opcional)"},"codigo_establecimiento":{"type":"string","maxLength":3,"example":"001","description":"C\u00f3digo de establecimiento (3 d\u00edgitos)"},"codigo_puntoemision":{"type":"string","maxLength":3,"example":"001","description":"C\u00f3digo de punto de emisi\u00f3n (3 d\u00edgitos)"},"direccion_matriz":{"type":"string","maxLength":300,"example":"Av. Principal 123","description":"Direcci\u00f3n de la matriz"},"direccion_establecimiento":{"type":"string","maxLength":300,"example":"Av. Sucursal 456","description":"Direcci\u00f3n del establecimiento"},"obligado_contabilidad":{"type":"string","enum":["SI","NO"],"example":"SI","description":"Obligado a llevar contabilidad (opcional)"},"contribuyente_especial":{"type":"string","maxLength":50,"example":"12345","description":"N\u00famero de contribuyente especial (opcional)"},"agente_retencion":{"type":"boolean","example":false,"description":"Agente de retenci\u00f3n (opcional)"},"gran_contribuyente":{"type":"boolean","example":false,"description":"Gran contribuyente (opcional)"},"calificacion_artesanal":{"type":"string","maxLength":50,"example":"","description":"Calificaci\u00f3n artesanal (opcional)"},"regimen_rimpe":{"type":"boolean","example":false,"description":"R\u00e9gimen RIMPE (opcional)"},"regimen_rimpe_popular":{"type":"boolean","example":false,"description":"R\u00e9gimen RIMPE Popular (opcional)"}}},"ambiente":{"type":"integer","enum":[1,2],"example":1,"description":"Ambiente: 1=Pruebas (GRATIS), 2=Producci\u00f3n (usa cr\u00e9ditos)"},"tipo_emision":{"type":"integer","enum":[1],"example":1,"description":"Tipo de emisi\u00f3n: 1=Normal (opcional, por defecto es 1)"},"transportista":{"type":"object","description":"Informaci\u00f3n del transportista","required":["tipo_identificacion","identificacion","razon_social"],"properties":{"tipo_identificacion":{"type":"string","maxLength":2,"example":"05","description":"Tipo de identificaci\u00f3n del transportista (04=RUC, 05=C\u00e9dula, 06=Pasaporte, 07=Consumidor Final, 08=Identificaci\u00f3n del exterior)"},"identificacion":{"type":"string","maxLength":20,"example":"1234567890","description":"N\u00famero de identificaci\u00f3n del transportista"},"razon_social":{"type":"string","maxLength":300,"example":"Transportes ABC","description":"Raz\u00f3n social o nombre del transportista"},"direccion":{"type":"string","maxLength":300,"example":"Av. Transporte 123","description":"Direcci\u00f3n del transportista (opcional)"},"telefono":{"type":"string","maxLength":300,"example":"022345678","description":"Tel\u00e9fono del transportista (opcional)"},"celular":{"type":"string","maxLength":300,"example":"0987654321","description":"Celular del transportista (opcional)"},"correo":{"type":"string","maxLength":300,"example":"transportista@ejemplo.com","description":"Correo electr\u00f3nico del transportista (opcional)"},"placa":{"type":"string","example":"ABC1234","description":"Placa del veh\u00edculo de transporte (opcional)"}}},"destinatario":{"type":"object","description":"Informaci\u00f3n del destinatario","required":["tipo_identificacion","identificacion","razon_social","direccion"],"properties":{"tipo_identificacion":{"type":"string","maxLength":2,"example":"05","description":"Tipo de identificaci\u00f3n del destinatario (04=RUC, 05=C\u00e9dula, 06=Pasaporte, 07=Consumidor Final, 08=Identificaci\u00f3n del exterior)"},"identificacion":{"type":"string","maxLength":20,"example":"0987654321","description":"N\u00famero de identificaci\u00f3n del destinatario"},"razon_social":{"type":"string","maxLength":300,"example":"Juan P\u00e9rez","description":"Nombre o raz\u00f3n social del destinatario"},"direccion":{"type":"string","maxLength":300,"example":"Calle Destino 789","description":"Direcci\u00f3n del destinatario"},"telefono":{"type":"string","maxLength":300,"example":"022345678","description":"Tel\u00e9fono del destinatario (opcional)"},"celular":{"type":"string","maxLength":300,"example":"0987654321","description":"Celular del destinatario (opcional)"},"correo":{"type":"string","maxLength":300,"example":"destinatario@ejemplo.com","description":"Correo electr\u00f3nico del destinatario (opcional)"},"nombre_sucursal":{"type":"string","maxLength":300,"example":"Sucursal Norte","description":"Nombre de la sucursal (opcional)"},"codigo_sucursal":{"type":"string","example":"002","description":"C\u00f3digo de la sucursal (opcional)"}}},"traslado":{"type":"object","description":"Informaci\u00f3n del traslado de mercanc\u00edas","required":["direccion_destino"],"properties":{"fecha_inicio_transporte":{"type":"string","example":"2024\/01\/15","description":"Fecha de inicio del transporte en formato YYYY\/MM\/DD (opcional)"},"fecha_fin_transporte":{"type":"string","example":"2024\/01\/16","description":"Fecha de fin del transporte en formato YYYY\/MM\/DD (opcional)"},"punto_partida":{"type":"string","example":"Bodega Central - Av. Principal 123","description":"Punto de partida del transporte (opcional)"},"direccion_destino":{"type":"string","example":"Cliente Final - Calle Destino 789","description":"Direcci\u00f3n de destino del transporte"},"ruta":{"type":"string","example":"Ruta Nacional E35","description":"Ruta del transporte (opcional)"},"motivo_traslado":{"type":"string","example":"Venta","description":"Motivo del traslado (opcional)"},"codigo_establecimiento_destino":{"type":"integer","example":2,"description":"C\u00f3digo del establecimiento de destino (opcional)"}}},"items":{"type":"array","description":"Detalle de productos\/mercanc\u00edas a transportar","minItems":1,"items":{"type":"object","required":["codigo_principal","descripcion","cantidad"],"properties":{"codigo_principal":{"type":"string","maxLength":25,"example":"PROD001","description":"C\u00f3digo principal del producto"},"codigo_auxiliar":{"type":"string","maxLength":25,"example":"AUX001","description":"C\u00f3digo auxiliar del producto (opcional)"},"descripcion":{"type":"string","maxLength":300,"example":"Producto de ejemplo para transportar","description":"Descripci\u00f3n del producto\/mercanc\u00eda"},"cantidad":{"type":"number","format":"float","example":10,"description":"Cantidad del producto a transportar"},"unidad_medida":{"type":"integer","example":1,"description":"Unidad de medida (opcional)"},"detalles_adicionales":{"type":"array","description":"Detalles adicionales del producto (opcional)","items":{"type":"object","properties":{"nombre":{"type":"string","maxLength":300,"example":"Peso","description":"Nombre del detalle"},"detalle":{"type":"string","maxLength":300,"example":"50 kg","description":"Valor del detalle"}}}}}}},"documento_sustento":{"type":"object","description":"Documento que sustenta el traslado (opcional)","properties":{"codigo_documento_sustento":{"type":"integer","example":1,"description":"C\u00f3digo del documento de sustento (01=Factura, etc.)"},"numero_documento_sustento":{"type":"string","example":"001001000000001","description":"N\u00famero del documento de sustento"},"fecha_emision_documento_sustento":{"type":"string","example":"2024\/01\/14","description":"Fecha de emisi\u00f3n del documento de sustento en formato YYYY\/MM\/DD"},"autorizacion_documento_sustento":{"type":"string","example":"1234567890123456789012345678901234567890123456789","description":"N\u00famero de autorizaci\u00f3n del documento de sustento"},"documento_aduanero":{"type":"string","example":"DAU123456","description":"Documento aduanero \u00fanico"}}},"informacion_adicional":{"type":"array","description":"Informaci\u00f3n adicional de la gu\u00eda de remisi\u00f3n (opcional)","items":{"type":"object","properties":{"nombre":{"type":"string","maxLength":300,"example":"Observaciones","description":"Nombre del campo adicional"},"detalle":{"type":"string","maxLength":300,"example":"Mercanc\u00eda fr\u00e1gil","description":"Detalle del campo adicional"}}}},"codigoDoc":{"type":"string","example":"06","description":"C\u00f3digo del documento (opcional, por defecto es 06 para gu\u00edas de remisi\u00f3n)"},"proceso":{"type":"string","enum":["Nuevo","Actualizar"],"example":"Nuevo","description":"Tipo de proceso (opcional, por defecto es Nuevo)"}}},"examples":{"guia_basica":{"summary":"Gu\u00eda de remisi\u00f3n b\u00e1sica","description":"Ejemplo de gu\u00eda de remisi\u00f3n simple para traslado de mercanc\u00edas","value":{"emisor":{"ruc":"0912345678001","secuencial":"000000001","fecha_emision":"2024\/01\/15","nombre_comercial":"Mi Empresa Comercial","razon_social":"MI EMPRESA S.A.","codigo_establecimiento":"001","codigo_puntoemision":"001","direccion_matriz":"Av. Principal 123","direccion_establecimiento":"Av. Sucursal 456","obligado_contabilidad":"SI"},"ambiente":1,"transportista":{"tipo_identificacion":"05","identificacion":"1234567890","razon_social":"Transportes ABC","placa":"ABC1234"},"destinatario":{"tipo_identificacion":"05","identificacion":"0987654321","razon_social":"Juan P\u00e9rez","direccion":"Calle Destino 789"},"traslado":{"fecha_inicio_transporte":"2024\/01\/15","fecha_fin_transporte":"2024\/01\/16","punto_partida":"Bodega Central - Av. Principal 123","direccion_destino":"Cliente Final - Calle Destino 789","motivo_traslado":"Venta"},"items":[{"codigo_principal":"PROD001","descripcion":"Producto de ejemplo para transportar","cantidad":10}]}}}}}},"x-code-samples":[{"lang":"curl","label":"cURL (Gu\u00eda b\u00e1sica)","source":"curl -X POST \"https:\/\/www.invoka.com.ec\/api\/guia\/emision\" \\\n  -H \"Content-Type: application\/json\" \\\n  -H \"X-API-KEY: tu-api-key-aqui\" \\\n  -d '{\n    \"emisor\": {\n      \"ruc\": \"0912345678001\",\n      \"secuencial\": \"000000001\",\n      \"fecha_emision\": \"2024\/01\/15\",\n      \"nombre_comercial\": \"Mi Empresa Comercial\",\n      \"razon_social\": \"MI EMPRESA S.A.\",\n      \"codigo_establecimiento\": \"001\",\n      \"codigo_puntoemision\": \"001\",\n      \"direccion_matriz\": \"Av. Principal 123\",\n      \"direccion_establecimiento\": \"Av. Sucursal 456\",\n      \"obligado_contabilidad\": \"SI\"\n    },\n    \"ambiente\": 1,\n    \"transportista\": {\n      \"tipo_identificacion\": \"05\",\n      \"identificacion\": \"1234567890\",\n      \"razon_social\": \"Transportes ABC\",\n      \"placa\": \"ABC1234\"\n    },\n    \"destinatario\": {\n      \"tipo_identificacion\": \"05\",\n      \"identificacion\": \"0987654321\",\n      \"razon_social\": \"Juan P\u00e9rez\",\n      \"direccion\": \"Calle Destino 789\"\n    },\n    \"traslado\": {\n      \"fecha_inicio_transporte\": \"2024\/01\/15\",\n      \"fecha_fin_transporte\": \"2024\/01\/16\",\n      \"punto_partida\": \"Bodega Central - Av. Principal 123\",\n      \"direccion_destino\": \"Cliente Final - Calle Destino 789\",\n      \"motivo_traslado\": \"Venta\"\n    },\n    \"items\": [\n      {\n        \"codigo_principal\": \"PROD001\",\n        \"descripcion\": \"Producto de ejemplo para transportar\",\n        \"cantidad\": 10.00\n      }\n    ]\n  }'"},{"lang":"javascript","label":"JavaScript (fetch)","source":"const guiaData = {\n  emisor: {\n    ruc: \"0912345678001\",\n    secuencial: \"000000001\",\n    fecha_emision: \"2024\/01\/15\",\n    nombre_comercial: \"Mi Empresa Comercial\",\n    razon_social: \"MI EMPRESA S.A.\",\n    codigo_establecimiento: \"001\",\n    codigo_puntoemision: \"001\",\n    direccion_matriz: \"Av. Principal 123\",\n    direccion_establecimiento: \"Av. Sucursal 456\",\n    obligado_contabilidad: \"SI\"\n  },\n  ambiente: 1, \/\/ 1=Pruebas (gratis), 2=Producci\u00f3n (usa cr\u00e9ditos)\n  transportista: {\n    tipo_identificacion: \"05\",\n    identificacion: \"1234567890\",\n    razon_social: \"Transportes ABC\",\n    placa: \"ABC1234\"\n  },\n  destinatario: {\n    tipo_identificacion: \"05\",\n    identificacion: \"0987654321\",\n    razon_social: \"Juan P\u00e9rez\",\n    direccion: \"Calle Destino 789\"\n  },\n  traslado: {\n    fecha_inicio_transporte: \"2024\/01\/15\",\n    fecha_fin_transporte: \"2024\/01\/16\",\n    punto_partida: \"Bodega Central - Av. Principal 123\",\n    direccion_destino: \"Cliente Final - Calle Destino 789\",\n    motivo_traslado: \"Venta\"\n  },\n  items: [\n    {\n      codigo_principal: \"PROD001\",\n      descripcion: \"Producto de ejemplo para transportar\",\n      cantidad: 10.00\n    }\n  ]\n};\n\nfetch(\"https:\/\/www.invoka.com.ec\/api\/guia\/emision\", {\n  method: \"POST\",\n  headers: {\n    \"Content-Type\": \"application\/json\",\n    \"X-API-KEY\": \"tu-api-key-aqui\"\n  },\n  body: JSON.stringify(guiaData)\n})\n.then(response => response.json())\n.then(data => {\n  if (data.creado) {\n    console.log(\"Gu\u00eda de remisi\u00f3n creada:\", data.claveacceso);\n    console.log(\"ID Comprobante:\", data.id_comprobante);\n  } else {\n    console.error(\"Error:\", data.errors);\n  }\n})\n.catch(error => console.error(\"Error:\", error));"},{"lang":"php","label":"PHP (cURL)","source":"<?php\n$guiaData = [\n    \"emisor\" => [\n        \"ruc\" => \"0912345678001\",\n        \"secuencial\" => \"000000001\",\n        \"fecha_emision\" => \"2024\/01\/15\",\n        \"nombre_comercial\" => \"Mi Empresa Comercial\",\n        \"razon_social\" => \"MI EMPRESA S.A.\",\n        \"codigo_establecimiento\" => \"001\",\n        \"codigo_puntoemision\" => \"001\",\n        \"direccion_matriz\" => \"Av. Principal 123\",\n        \"direccion_establecimiento\" => \"Av. Sucursal 456\",\n        \"obligado_contabilidad\" => \"SI\"\n    ],\n    \"ambiente\" => 1, \/\/ 1=Pruebas (gratis), 2=Producci\u00f3n (usa cr\u00e9ditos)\n    \"transportista\" => [\n        \"tipo_identificacion\" => \"05\",\n        \"identificacion\" => \"1234567890\",\n        \"razon_social\" => \"Transportes ABC\",\n        \"placa\" => \"ABC1234\"\n    ],\n    \"destinatario\" => [\n        \"tipo_identificacion\" => \"05\",\n        \"identificacion\" => \"0987654321\",\n        \"razon_social\" => \"Juan P\u00e9rez\",\n        \"direccion\" => \"Calle Destino 789\"\n    ],\n    \"traslado\" => [\n        \"fecha_inicio_transporte\" => \"2024\/01\/15\",\n        \"fecha_fin_transporte\" => \"2024\/01\/16\",\n        \"punto_partida\" => \"Bodega Central - Av. Principal 123\",\n        \"direccion_destino\" => \"Cliente Final - Calle Destino 789\",\n        \"motivo_traslado\" => \"Venta\"\n    ],\n    \"items\" => [\n        [\n            \"codigo_principal\" => \"PROD001\",\n            \"descripcion\" => \"Producto de ejemplo para transportar\",\n            \"cantidad\" => 10.00\n        ]\n    ]\n];\n\n$curl = curl_init();\n\ncurl_setopt_array($curl, [\n    CURLOPT_URL => \"https:\/\/www.invoka.com.ec\/api\/guia\/emision\",\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_POST => true,\n    CURLOPT_POSTFIELDS => json_encode($guiaData),\n    CURLOPT_HTTPHEADER => [\n        \"Content-Type: application\/json\",\n        \"X-API-KEY: tu-api-key-aqui\"\n    ],\n]);\n\n$response = curl_exec($curl);\n$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);\ncurl_close($curl);\n\n$data = json_decode($response, true);\n\nif ($httpCode == 200 && $data[\\\"creado\\\"]) {\n    echo \"Gu\u00eda de remisi\u00f3n creada exitosamente:\\n\";\n    echo \"Clave de acceso: \" . $data[\\\"claveacceso\\\"] . \"\\n\";\n    echo \"ID Comprobante: \" . $data[\\\"id_comprobante\\\"] . \"\\n\";\n} else {\n    echo \"Error en la emisi\u00f3n:\\n\";\n    if (isset($data[\\\"errors\\\"])) {\n        print_r($data[\\\"errors\\\"]);\n    }\n}\n?>"},{"lang":"python","label":"Python (requests)","source":"import requests\nimport json\n\nguia_data = {\n    \"emisor\": {\n        \"ruc\": \"0912345678001\",\n        \"secuencial\": \"000000001\",\n        \"fecha_emision\": \"2024\/01\/15\",\n        \"nombre_comercial\": \"Mi Empresa Comercial\",\n        \"razon_social\": \"MI EMPRESA S.A.\",\n        \"codigo_establecimiento\": \"001\",\n        \"codigo_puntoemision\": \"001\",\n        \"direccion_matriz\": \"Av. Principal 123\",\n        \"direccion_establecimiento\": \"Av. Sucursal 456\",\n        \"obligado_contabilidad\": \"SI\"\n    },\n    \"ambiente\": 1,  # 1=Pruebas (gratis), 2=Producci\u00f3n (usa cr\u00e9ditos)\n    \"transportista\": {\n        \"tipo_identificacion\": \"05\",\n        \"identificacion\": \"1234567890\",\n        \"razon_social\": \"Transportes ABC\",\n        \"placa\": \"ABC1234\"\n    },\n    \"destinatario\": {\n        \"tipo_identificacion\": \"05\",\n        \"identificacion\": \"0987654321\",\n        \"razon_social\": \"Juan P\u00e9rez\",\n        \"direccion\": \"Calle Destino 789\"\n    },\n    \"traslado\": {\n        \"fecha_inicio_transporte\": \"2024\/01\/15\",\n        \"fecha_fin_transporte\": \"2024\/01\/16\",\n        \"punto_partida\": \"Bodega Central - Av. Principal 123\",\n        \"direccion_destino\": \"Cliente Final - Calle Destino 789\",\n        \"motivo_traslado\": \"Venta\"\n    },\n    \"items\": [\n        {\n            \"codigo_principal\": \"PROD001\",\n            \"descripcion\": \"Producto de ejemplo para transportar\",\n            \"cantidad\": 10.00\n        }\n    ]\n}\n\nurl = \"https:\/\/www.invoka.com.ec\/api\/guia\/emision\"\nheaders = {\n    \"Content-Type\": \"application\/json\",\n    \"X-API-KEY\": \"tu-api-key-aqui\"\n}\n\ntry:\n    response = requests.post(url, headers=headers, json=guia_data)\n    response.raise_for_status()\n\n    data = response.json()\n\n    if data.get(\"creado\"):\n        print(f\"Gu\u00eda de remisi\u00f3n creada exitosamente:\")\n        print(f\"Clave de acceso: {data[\\\"claveacceso\\\"]}\")\n        print(f\"ID Comprobante: {data[\\\"id_comprobante\\\"]}\")\n    else:\n        print(f\"Error en la emisi\u00f3n:\")\n        if \\\"errors\\\" in data:\n            print(\"Detalles del error:\")\n            print(json.dumps(data[\\\"errors\\\"], indent=2))\n\nexcept requests.exceptions.RequestException as e:\n    print(f\"Error de conexi\u00f3n: {e}\")\nexcept json.JSONDecodeError as e:\n    print(f\"Error al decodificar respuesta: {e}\")"}],"responses":{"200":{"description":"Gu\u00eda de remisi\u00f3n registrada exitosamente para procesamiento","content":{"application\/json":{"schema":{"type":"object","properties":{"creado":{"type":"boolean","example":true,"description":"Indica si la gu\u00eda de remisi\u00f3n fue creada exitosamente"},"claveacceso":{"type":"string","example":"1501202406091234567800110010010000000011234567890","description":"Clave de acceso del comprobante generada"},"id_comprobante":{"type":"integer","example":12345,"description":"ID interno del comprobante en la base de datos"}}}}}},"400":{"description":"Error en los datos enviados","content":{"application\/json":{"schema":{"type":"object","properties":{"creado":{"type":"boolean","example":false},"errors":{"type":"array","description":"Lista de errores de validaci\u00f3n","items":{"type":"string"},"example":["El campo emisor.ruc es obligatorio.","El campo traslado.direccion_destino es obligatorio."]}}}}}},"401":{"description":"API Key inv\u00e1lida o empresa no existe","content":{"application\/json":{"schema":{"type":"object","properties":{"creado":{"type":"boolean","example":false},"errors":{"type":"array","items":{"type":"string"},"example":["Api_key No existe"]}}}}}},"500":{"description":"Error interno del servidor","content":{"application\/json":{"schema":{"type":"object","properties":{"creado":{"type":"boolean","example":false},"errors":{"type":"array","items":{"type":"string"},"example":["Error en creacion"]}}}}}},"429":{"description":"M\u00e1s de 300 peticiones por minuto por API key"}},"operationId":"emitir_guia_remision"}},"\/api\/retencionats\/emision":{"post":{"tags":["Comprobantes de Retenci\u00f3n"],"summary":"Emitir comprobante de retenci\u00f3n 2.0.0 (ATS) \u00b7 recomendada","description":"**Versi\u00f3n 2.0.0 del SRI** (obligatoria para el ATS): adem\u00e1s de las retenciones incluye el detalle del documento sustento (items o gastos, impuestos, forma de pago) y, para dividendos (codigo_sustento_tributario 10), el bloque `dividendos`.\n\nCrea y procesa un comprobante de retenci\u00f3n electr\u00f3nico (C\u00f3digo 07) seg\u00fan normativa SRI Ecuador.\n\n**IMPORTANTE:**\n- **Ambiente 1 (Pruebas)**: GRATIS e ilimitado - Para desarrollo y testing\n- **Ambiente 2 (Producci\u00f3n)**: Usa 1 cr\u00e9dito por comprobante de retenci\u00f3n autorizado\n- Las retenciones se emiten cuando se realizan pagos sujetos a retenci\u00f3n\n- Debe incluir informaci\u00f3n del documento sustento (factura, liquidaci\u00f3n, etc.)\n- **Formato de fecha**: YYYY\/MM\/DD (con barras, ejemplo: 2024\/01\/15). **La fecha de emisi\u00f3n debe ser la del d\u00eda** (hora de Ecuador): por normativa del SRI no se aceptan comprobantes con fecha anterior ni posterior.\n\n**ESTRUCTURA DE DATOS:**\n- **Emisor**: Datos de la empresa que emite (incluye secuencial y fecha de emisi\u00f3n)\n- **Proveedor**: Datos del sujeto al que se le retiene\n- **Sustento**: Informaci\u00f3n del documento que sustenta la retenci\u00f3n (factura, liquidaci\u00f3n, etc.)\n  - Puede incluir **items** (productos\/servicios) O **gastos** (subtotales por tipo de IVA)\n- **Retenciones**: Array de retenciones aplicadas (IVA, Renta, ISD)\n- **Informaci\u00f3n adicional**: Campos personalizados (opcional)","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["emisor","ambiente","codigoDoc","proveedor","sustento","retenciones"],"properties":{"emisor":{"type":"object","description":"Informaci\u00f3n del emisor\/empresa","required":["ruc","secuencial","fecha_emision","nombre_comercial","codigo_establecimiento","codigo_puntoemision","direccion_matriz","direccion_establecimiento"],"properties":{"ruc":{"type":"string","maxLength":13,"example":"0912345678001","description":"RUC del emisor (13 d\u00edgitos)"},"secuencial":{"type":"string","maxLength":9,"example":"000000001","description":"N\u00famero secuencial del comprobante de retenci\u00f3n (9 d\u00edgitos)"},"fecha_emision":{"type":"string","example":"2024\/01\/15","description":"Fecha de emisi\u00f3n en formato YYYY\/MM\/DD (con barras)"},"nombre_comercial":{"type":"string","maxLength":300,"example":"Mi Empresa Comercial","description":"Nombre comercial del emisor"},"razon_social":{"type":"string","maxLength":300,"example":"MI EMPRESA S.A.","description":"Raz\u00f3n social del emisor (opcional)"},"codigo_establecimiento":{"type":"string","maxLength":3,"example":"001","description":"C\u00f3digo de establecimiento (3 d\u00edgitos)"},"codigo_puntoemision":{"type":"string","maxLength":3,"example":"001","description":"C\u00f3digo de punto de emisi\u00f3n (3 d\u00edgitos)"},"direccion_matriz":{"type":"string","maxLength":300,"example":"Av. Principal 123","description":"Direcci\u00f3n de la matriz"},"direccion_establecimiento":{"type":"string","maxLength":300,"example":"Av. Sucursal 456","description":"Direcci\u00f3n del establecimiento"},"obligado_contabilidad":{"type":"string","enum":["SI","NO"],"example":"SI","description":"Obligado a llevar contabilidad (opcional)"},"contribuyente_especial":{"type":"string","maxLength":50,"example":"12345","description":"N\u00famero de contribuyente especial (opcional)"},"agente_retencion":{"type":"boolean","example":true,"description":"Agente de retenci\u00f3n (opcional)"},"gran_contribuyente":{"type":"boolean","example":false,"description":"Gran contribuyente (opcional)"},"regimen_rimpe":{"type":"boolean","example":false,"description":"R\u00e9gimen RIMPE (opcional)"},"regimen_rimpe_popular":{"type":"boolean","example":false,"description":"R\u00e9gimen RIMPE Popular (opcional)"}}},"ambiente":{"type":"integer","enum":[1,2],"example":1,"description":"Ambiente: 1=Pruebas (GRATIS), 2=Producci\u00f3n (usa cr\u00e9ditos)"},"codigoDoc":{"type":"string","example":"07","description":"C\u00f3digo del documento (07 para comprobantes de retenci\u00f3n)"},"proveedor":{"type":"object","description":"Informaci\u00f3n del proveedor\/sujeto retenido","required":["tipo_identificacion","identificacion","razon_social","direccion"],"properties":{"tipo_identificacion":{"type":"string","maxLength":2,"example":"04","description":"Tipo de identificaci\u00f3n del proveedor (04=RUC, 05=C\u00e9dula, 06=Pasaporte, 07=Consumidor Final, 08=Identificaci\u00f3n del exterior)"},"identificacion":{"type":"string","maxLength":20,"example":"0912345678001","description":"N\u00famero de identificaci\u00f3n del proveedor"},"razon_social":{"type":"string","maxLength":300,"example":"PROVEEDOR EJEMPLO S.A.","description":"Raz\u00f3n social del proveedor"},"direccion":{"type":"string","maxLength":300,"example":"Av. Proveedor 789","description":"Direcci\u00f3n del proveedor"},"telefono":{"type":"string","maxLength":300,"example":"022345678","description":"Tel\u00e9fono del proveedor (opcional)"},"celular":{"type":"string","maxLength":300,"example":"0987654321","description":"Celular del proveedor (opcional)"},"correo":{"type":"string","maxLength":300,"example":"proveedor@ejemplo.com","description":"Correo electr\u00f3nico del proveedor (opcional)"}}},"sustento":{"type":"object","description":"Informaci\u00f3n del documento que sustenta la retenci\u00f3n","required":["codigo_sustento_tributario","codigo_documento_sustento","numero_documento_sustento","numero_autorizacion","fecha_documento_sustento","fecha_registro_contable"],"properties":{"codigo_sustento_tributario":{"type":"string","example":"01","description":"C\u00f3digo del sustento tributario seg\u00fan tabla SRI (01=Cr\u00e9dito Tributario IVA, 02=Costo o Gasto, etc.)"},"codigo_documento_sustento":{"type":"string","example":"01","description":"C\u00f3digo del tipo de documento (01=Factura, 03=Liquidaci\u00f3n de compra, etc.)"},"numero_documento_sustento":{"type":"string","example":"001001000000001","description":"N\u00famero del documento sustento (15 d\u00edgitos sin guiones)"},"numero_autorizacion":{"type":"string","example":"1234567890123456789012345678901234567890123456789","description":"N\u00famero de autorizaci\u00f3n del documento sustento (49 d\u00edgitos electr\u00f3nico, 10 d\u00edgitos f\u00edsico)"},"fecha_documento_sustento":{"type":"string","example":"2024\/01\/10","description":"Fecha de emisi\u00f3n del documento sustento en formato YYYY\/MM\/DD"},"fecha_registro_contable":{"type":"string","example":"2024\/01\/10","description":"Fecha de registro contable en formato YYYY\/MM\/DD"},"items":{"type":"array","description":"Detalle de productos\/servicios del documento sustento (usar items O gastos, no ambos)","items":{"type":"object","required":["codigo_principal","descripcion","tipo_iva","precio_unitario","cantidad"],"properties":{"codigo_principal":{"type":"string","maxLength":25,"example":"PROD001","description":"C\u00f3digo principal del producto"},"codigo_auxiliar":{"type":"string","maxLength":25,"example":"AUX001","description":"C\u00f3digo auxiliar (opcional)"},"descripcion":{"type":"string","maxLength":300,"example":"Servicio de consultor\u00eda","description":"Descripci\u00f3n del producto\/servicio"},"tipo_iva":{"type":"integer","example":2,"description":"Tipo de IVA (0=0%, 2=12%, etc.)"},"precio_unitario":{"type":"number","format":"float","example":100,"description":"Precio unitario"},"cantidad":{"type":"number","format":"float","example":1,"description":"Cantidad"},"descuento":{"type":"number","format":"float","example":0,"description":"Descuento aplicado (opcional)"},"tipo_ice":{"type":"number","example":0,"description":"Tipo de ICE (opcional)"},"valor_ice":{"type":"number","format":"float","example":0,"description":"Valor ICE (opcional)"}}}},"gastos":{"type":"array","description":"Detalle por tipo de gasto\/IVA (usar items O gastos, no ambos)","items":{"type":"object","required":["descripcion","subtotal_iva","subtotal_siniva","subtotal_ivacero","tipo_iva"],"properties":{"descripcion":{"type":"string","maxLength":300,"example":"Servicios profesionales","description":"Descripci\u00f3n del gasto"},"subtotal_iva":{"type":"number","format":"float","example":100,"description":"Subtotal gravado con IVA"},"subtotal_siniva":{"type":"number","format":"float","example":0,"description":"Subtotal sin IVA"},"subtotal_ivacero":{"type":"number","format":"float","example":0,"description":"Subtotal IVA 0%"},"tipo_iva":{"type":"integer","example":2,"description":"Tipo de IVA aplicado"},"tipo_ice":{"type":"number","example":0,"description":"Tipo de ICE (opcional)"},"tarifa_ice":{"type":"number","format":"float","example":0,"description":"Tarifa ICE (opcional)"},"valor_ice":{"type":"number","format":"float","example":0,"description":"Valor ICE (opcional)"}}}}}},"retenciones":{"type":"array","description":"Detalle de retenciones aplicadas","minItems":1,"items":{"type":"object","required":["base_imponible","codigoimpuesto","codigo_retencion","porcentaje_retencion","valor_retenido"],"properties":{"base_imponible":{"type":"number","format":"float","example":100,"description":"Base imponible de la retenci\u00f3n"},"codigoimpuesto":{"type":"integer","example":2,"description":"C\u00f3digo del impuesto (1=Renta, 2=IVA, 6=ISD)"},"codigo_retencion":{"type":"string","example":"10","description":"C\u00f3digo de la retenci\u00f3n seg\u00fan tabla SRI (ej: 10, 20, 303, 304, etc.)"},"porcentaje_retencion":{"type":"number","format":"float","example":10,"description":"Porcentaje de retenci\u00f3n"},"valor_retenido":{"type":"number","format":"float","example":10,"description":"Valor retenido calculado"}}}},"informacion_adicional":{"type":"array","description":"Informaci\u00f3n adicional del comprobante (opcional)","items":{"type":"object","properties":{"nombre":{"type":"string","maxLength":300,"example":"Observaciones","description":"Nombre del campo adicional"},"detalle":{"type":"string","maxLength":300,"example":"Retenci\u00f3n sobre factura 001-001-000000001","description":"Detalle del campo adicional"}}}}}},"examples":{"retencion_basica":{"summary":"Comprobante de retenci\u00f3n b\u00e1sico","description":"Ejemplo de comprobante de retenci\u00f3n simple sobre una factura","value":{"emisor":{"ruc":"0912345678001","secuencial":"000000001","fecha_emision":"2024\/01\/15","nombre_comercial":"Mi Empresa Comercial","razon_social":"MI EMPRESA S.A.","codigo_establecimiento":"001","codigo_puntoemision":"001","direccion_matriz":"Av. Principal 123","direccion_establecimiento":"Av. Sucursal 456","obligado_contabilidad":"SI","agente_retencion":true},"ambiente":1,"codigoDoc":"07","proveedor":{"tipo_identificacion":"04","identificacion":"0987654321001","razon_social":"PROVEEDOR EJEMPLO S.A.","direccion":"Av. Proveedor 789","correo":"proveedor@ejemplo.com"},"sustento":{"codigo_sustento_tributario":"01","codigo_documento_sustento":"01","numero_documento_sustento":"001001000000001","numero_autorizacion":"1234567890123456789012345678901234567890123456789","fecha_documento_sustento":"2024\/01\/10","fecha_registro_contable":"2024\/01\/10","gastos":[{"descripcion":"Servicios profesionales","subtotal_iva":100,"subtotal_siniva":0,"subtotal_ivacero":0,"tipo_iva":2}]},"retenciones":[{"base_imponible":100,"codigoimpuesto":1,"codigo_retencion":"303","porcentaje_retencion":1,"valor_retenido":1},{"base_imponible":12,"codigoimpuesto":2,"codigo_retencion":"10","porcentaje_retencion":30,"valor_retenido":3.6}]}}}}}},"x-code-samples":[{"lang":"curl","label":"cURL (Retenci\u00f3n b\u00e1sica)","source":"curl -X POST \"https:\/\/www.invoka.com.ec\/api\/retencion\/emision\" \\\n  -H \"Content-Type: application\/json\" \\\n  -H \"X-API-KEY: tu-api-key-aqui\" \\\n  -d '{\n    \"emisor\": {\n      \"ruc\": \"0912345678001\",\n      \"secuencial\": \"000000001\",\n      \"fecha_emision\": \"2024\/01\/15\",\n      \"nombre_comercial\": \"Mi Empresa Comercial\",\n      \"razon_social\": \"MI EMPRESA S.A.\",\n      \"codigo_establecimiento\": \"001\",\n      \"codigo_puntoemision\": \"001\",\n      \"direccion_matriz\": \"Av. Principal 123\",\n      \"direccion_establecimiento\": \"Av. Sucursal 456\",\n      \"obligado_contabilidad\": \"SI\",\n      \"agente_retencion\": true\n    },\n    \"ambiente\": 1,\n    \"codigoDoc\": \"07\",\n    \"proveedor\": {\n      \"tipo_identificacion\": \"04\",\n      \"identificacion\": \"0987654321001\",\n      \"razon_social\": \"PROVEEDOR EJEMPLO S.A.\",\n      \"direccion\": \"Av. Proveedor 789\",\n      \"correo\": \"proveedor@ejemplo.com\"\n    },\n    \"sustento\": {\n      \"codigo_sustento_tributario\": \"01\",\n      \"codigo_documento_sustento\": \"01\",\n      \"numero_documento_sustento\": \"001001000000001\",\n      \"numero_autorizacion\": \"1234567890123456789012345678901234567890123456789\",\n      \"fecha_documento_sustento\": \"2024\/01\/10\",\n      \"fecha_registro_contable\": \"2024\/01\/10\",\n      \"gastos\": [\n        {\n          \"descripcion\": \"Servicios profesionales\",\n          \"subtotal_iva\": 100.00,\n          \"subtotal_siniva\": 0.00,\n          \"subtotal_ivacero\": 0.00,\n          \"tipo_iva\": 2\n        }\n      ]\n    },\n    \"retenciones\": [\n      {\n        \"base_imponible\": 100.00,\n        \"codigoimpuesto\": 1,\n        \"codigo_retencion\": \"303\",\n        \"porcentaje_retencion\": 1.00,\n        \"valor_retenido\": 1.00\n      },\n      {\n        \"base_imponible\": 12.00,\n        \"codigoimpuesto\": 2,\n        \"codigo_retencion\": \"10\",\n        \"porcentaje_retencion\": 30.00,\n        \"valor_retenido\": 3.60\n      }\n    ]\n  }'"},{"lang":"javascript","label":"JavaScript (fetch)","source":"const retencionData = {\n  emisor: {\n    ruc: \"0912345678001\",\n    secuencial: \"000000001\",\n    fecha_emision: \"2024\/01\/15\",\n    nombre_comercial: \"Mi Empresa Comercial\",\n    razon_social: \"MI EMPRESA S.A.\",\n    codigo_establecimiento: \"001\",\n    codigo_puntoemision: \"001\",\n    direccion_matriz: \"Av. Principal 123\",\n    direccion_establecimiento: \"Av. Sucursal 456\",\n    obligado_contabilidad: \"SI\",\n    agente_retencion: true\n  },\n  ambiente: 1, \/\/ 1=Pruebas (gratis), 2=Producci\u00f3n (usa cr\u00e9ditos)\n  codigoDoc: \"07\",\n  proveedor: {\n    tipo_identificacion: \"04\",\n    identificacion: \"0987654321001\",\n    razon_social: \"PROVEEDOR EJEMPLO S.A.\",\n    direccion: \"Av. Proveedor 789\",\n    correo: \"proveedor@ejemplo.com\"\n  },\n  sustento: {\n    codigo_sustento_tributario: \"01\",\n    codigo_documento_sustento: \"01\",\n    numero_documento_sustento: \"001001000000001\",\n    numero_autorizacion: \"1234567890123456789012345678901234567890123456789\",\n    fecha_documento_sustento: \"2024\/01\/10\",\n    fecha_registro_contable: \"2024\/01\/10\",\n    gastos: [\n      {\n        descripcion: \"Servicios profesionales\",\n        subtotal_iva: 100.00,\n        subtotal_siniva: 0.00,\n        subtotal_ivacero: 0.00,\n        tipo_iva: 2\n      }\n    ]\n  },\n  retenciones: [\n    {\n      base_imponible: 100.00,\n      codigoimpuesto: 1,\n      codigo_retencion: \"303\",\n      porcentaje_retencion: 1.00,\n      valor_retenido: 1.00\n    },\n    {\n      base_imponible: 12.00,\n      codigoimpuesto: 2,\n      codigo_retencion: \"10\",\n      porcentaje_retencion: 30.00,\n      valor_retenido: 3.60\n    }\n  ]\n};\n\nfetch(\"https:\/\/www.invoka.com.ec\/api\/retencion\/emision\", {\n  method: \"POST\",\n  headers: {\n    \"Content-Type\": \"application\/json\",\n    \"X-API-KEY\": \"tu-api-key-aqui\"\n  },\n  body: JSON.stringify(retencionData)\n})\n.then(response => response.json())\n.then(data => {\n  if (data.creado) {\n    console.log(\"Retenci\u00f3n creada:\", data.claveacceso);\n    console.log(\"ID Comprobante:\", data.id_comprobante);\n  } else {\n    console.error(\"Error:\", data.errors);\n  }\n})\n.catch(error => console.error(\"Error:\", error));"},{"lang":"php","label":"PHP (cURL)","source":"<?php\n$retencionData = [\n    \"emisor\" => [\n        \"ruc\" => \"0912345678001\",\n        \"secuencial\" => \"000000001\",\n        \"fecha_emision\" => \"2024\/01\/15\",\n        \"nombre_comercial\" => \"Mi Empresa Comercial\",\n        \"razon_social\" => \"MI EMPRESA S.A.\",\n        \"codigo_establecimiento\" => \"001\",\n        \"codigo_puntoemision\" => \"001\",\n        \"direccion_matriz\" => \"Av. Principal 123\",\n        \"direccion_establecimiento\" => \"Av. Sucursal 456\",\n        \"obligado_contabilidad\" => \"SI\",\n        \"agente_retencion\" => true\n    ],\n    \"ambiente\" => 1, \/\/ 1=Pruebas (gratis), 2=Producci\u00f3n (usa cr\u00e9ditos)\n    \"codigoDoc\" => \"07\",\n    \"proveedor\" => [\n        \"tipo_identificacion\" => \"04\",\n        \"identificacion\" => \"0987654321001\",\n        \"razon_social\" => \"PROVEEDOR EJEMPLO S.A.\",\n        \"direccion\" => \"Av. Proveedor 789\",\n        \"correo\" => \"proveedor@ejemplo.com\"\n    ],\n    \"sustento\" => [\n        \"codigo_sustento_tributario\" => \"01\",\n        \"codigo_documento_sustento\" => \"01\",\n        \"numero_documento_sustento\" => \"001001000000001\",\n        \"numero_autorizacion\" => \"1234567890123456789012345678901234567890123456789\",\n        \"fecha_documento_sustento\" => \"2024\/01\/10\",\n        \"fecha_registro_contable\" => \"2024\/01\/10\",\n        \"gastos\" => [\n            [\n                \"descripcion\" => \"Servicios profesionales\",\n                \"subtotal_iva\" => 100.00,\n                \"subtotal_siniva\" => 0.00,\n                \"subtotal_ivacero\" => 0.00,\n                \"tipo_iva\" => 2\n            ]\n        ]\n    ],\n    \"retenciones\" => [\n        [\n            \"base_imponible\" => 100.00,\n            \"codigoimpuesto\" => 1,\n            \"codigo_retencion\" => \"303\",\n            \"porcentaje_retencion\" => 1.00,\n            \"valor_retenido\" => 1.00\n        ],\n        [\n            \"base_imponible\" => 12.00,\n            \"codigoimpuesto\" => 2,\n            \"codigo_retencion\" => \"10\",\n            \"porcentaje_retencion\" => 30.00,\n            \"valor_retenido\" => 3.60\n        ]\n    ]\n];\n\n$curl = curl_init();\n\ncurl_setopt_array($curl, [\n    CURLOPT_URL => \"https:\/\/www.invoka.com.ec\/api\/retencion\/emision\",\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_POST => true,\n    CURLOPT_POSTFIELDS => json_encode($retencionData),\n    CURLOPT_HTTPHEADER => [\n        \"Content-Type: application\/json\",\n        \"X-API-KEY: tu-api-key-aqui\"\n    ],\n]);\n\n$response = curl_exec($curl);\n$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);\ncurl_close($curl);\n\n$data = json_decode($response, true);\n\nif ($httpCode == 200 && $data[\\\"creado\\\"]) {\n    echo \"Retenci\u00f3n creada exitosamente:\\n\";\n    echo \"Clave de acceso: \" . $data[\\\"claveacceso\\\"] . \"\\n\";\n    echo \"ID Comprobante: \" . $data[\\\"id_comprobante\\\"] . \"\\n\";\n} else {\n    echo \"Error en la emisi\u00f3n:\\n\";\n    if (isset($data[\\\"errors\\\"])) {\n        print_r($data[\\\"errors\\\"]);\n    }\n}\n?>"},{"lang":"python","label":"Python (requests)","source":"import requests\nimport json\n\nretencion_data = {\n    \"emisor\": {\n        \"ruc\": \"0912345678001\",\n        \"secuencial\": \"000000001\",\n        \"fecha_emision\": \"2024\/01\/15\",\n        \"nombre_comercial\": \"Mi Empresa Comercial\",\n        \"razon_social\": \"MI EMPRESA S.A.\",\n        \"codigo_establecimiento\": \"001\",\n        \"codigo_puntoemision\": \"001\",\n        \"direccion_matriz\": \"Av. Principal 123\",\n        \"direccion_establecimiento\": \"Av. Sucursal 456\",\n        \"obligado_contabilidad\": \"SI\",\n        \"agente_retencion\": True\n    },\n    \"ambiente\": 1,  # 1=Pruebas (gratis), 2=Producci\u00f3n (usa cr\u00e9ditos)\n    \"codigoDoc\": \"07\",\n    \"proveedor\": {\n        \"tipo_identificacion\": \"04\",\n        \"identificacion\": \"0987654321001\",\n        \"razon_social\": \"PROVEEDOR EJEMPLO S.A.\",\n        \"direccion\": \"Av. Proveedor 789\",\n        \"correo\": \"proveedor@ejemplo.com\"\n    },\n    \"sustento\": {\n        \"codigo_sustento_tributario\": \"01\",\n        \"codigo_documento_sustento\": \"01\",\n        \"numero_documento_sustento\": \"001001000000001\",\n        \"numero_autorizacion\": \"1234567890123456789012345678901234567890123456789\",\n        \"fecha_documento_sustento\": \"2024\/01\/10\",\n        \"fecha_registro_contable\": \"2024\/01\/10\",\n        \"gastos\": [\n            {\n                \"descripcion\": \"Servicios profesionales\",\n                \"subtotal_iva\": 100.00,\n                \"subtotal_siniva\": 0.00,\n                \"subtotal_ivacero\": 0.00,\n                \"tipo_iva\": 2\n            }\n        ]\n    },\n    \"retenciones\": [\n        {\n            \"base_imponible\": 100.00,\n            \"codigoimpuesto\": 1,\n            \"codigo_retencion\": \"303\",\n            \"porcentaje_retencion\": 1.00,\n            \"valor_retenido\": 1.00\n        },\n        {\n            \"base_imponible\": 12.00,\n            \"codigoimpuesto\": 2,\n            \"codigo_retencion\": \"10\",\n            \"porcentaje_retencion\": 30.00,\n            \"valor_retenido\": 3.60\n        }\n    ]\n}\n\nurl = \"https:\/\/www.invoka.com.ec\/api\/retencion\/emision\"\nheaders = {\n    \"Content-Type\": \"application\/json\",\n    \"X-API-KEY\": \"tu-api-key-aqui\"\n}\n\ntry:\n    response = requests.post(url, headers=headers, json=retencion_data)\n    response.raise_for_status()\n\n    data = response.json()\n\n    if data.get(\"creado\"):\n        print(f\"Retenci\u00f3n creada exitosamente:\")\n        print(f\"Clave de acceso: {data[\\\"claveacceso\\\"]}\")\n        print(f\"ID Comprobante: {data[\\\"id_comprobante\\\"]}\")\n    else:\n        print(f\"Error en la emisi\u00f3n:\")\n        if \\\"errors\\\" in data:\n            print(\"Detalles del error:\")\n            print(json.dumps(data[\\\"errors\\\"], indent=2))\n\nexcept requests.exceptions.RequestException as e:\n    print(f\"Error de conexi\u00f3n: {e}\")\nexcept json.JSONDecodeError as e:\n    print(f\"Error al decodificar respuesta: {e}\")"}],"responses":{"200":{"description":"Comprobante de retenci\u00f3n registrado exitosamente para procesamiento","content":{"application\/json":{"schema":{"type":"object","properties":{"creado":{"type":"boolean","example":true,"description":"Indica si el comprobante fue creado exitosamente"},"claveacceso":{"type":"string","example":"1501202407091234567800110010010000000011234567890","description":"Clave de acceso del comprobante generada"},"id_comprobante":{"type":"integer","example":12345,"description":"ID interno del comprobante en la base de datos"}}}}}},"400":{"description":"Error en los datos enviados","content":{"application\/json":{"schema":{"type":"object","properties":{"creado":{"type":"boolean","example":false},"errors":{"type":"array","description":"Lista de errores de validaci\u00f3n","items":{"type":"string"},"example":["El campo emisor.ruc es obligatorio.","Debe tener un sustento ya sea mediante un items o un gasto"]}}}}}},"401":{"description":"API Key inv\u00e1lida","content":{"application\/json":{"schema":{"type":"object","properties":{"creado":{"type":"boolean","example":false},"errors":{"type":"array","items":{"type":"string"},"example":["API Key requerida en header X-API-KEY"]}}}}}},"500":{"description":"Error interno del servidor","content":{"application\/json":{"schema":{"type":"object","properties":{"creado":{"type":"boolean","example":false},"errors":{"type":"array","items":{"type":"string"},"example":["Error interno del servidor"]}}}}}},"429":{"description":"M\u00e1s de 300 peticiones por minuto por API key"}},"operationId":"emitir_retencion_ats"}},"\/api\/retencion\/emision":{"post":{"tags":["Comprobantes de Retenci\u00f3n"],"summary":"Emitir comprobante de retenci\u00f3n 1.0.0 (obsoleta)","deprecated":true,"description":"**Obsoleta: para integraciones nuevas use `\/api\/retencionats\/emision` (retenci\u00f3n 2.0.0, la que pide el ATS).** Esta ruta sigue funcionando igual para quienes ya la usan.\n\n**Versi\u00f3n 1.0.0 del SRI**: una retenci\u00f3n por impuesto, cada una con su documento sustento. No lleva el detalle de la compra.\n\nSi el JSON incluye `sustento`, la petici\u00f3n se procesa autom\u00e1ticamente como **retenci\u00f3n 2.0.0 (ATS)** (ver `\/api\/retencionats\/emision`).\n\n**C\u00f3digos**: `codigoimpuesto` 1 = Renta, 2 = IVA, 6 = ISD. `codigo_retencion` seg\u00fan la tabla del SRI (p. ej. 312 renta 2 %; IVA: 1 = 30 %, 2 = 70 %, 3 = 100 %). El `valor_retenido` se calcula como base \u00d7 porcentaje; el SRI valida que el porcentaje corresponda al c\u00f3digo.\n\n**Ambiente 1** gratis e ilimitado; **ambiente 2** consume 1 cr\u00e9dito por comprobante autorizado.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["ambiente","emisor","proveedor","retenciones"],"properties":{"ambiente":{"type":"integer","enum":[1,2],"example":1},"emisor":{"type":"object","description":"Empresa emisora (ruc, secuencial, fecha_emision Y\/m\/d, codigo_establecimiento, codigo_puntoemision, direccion_matriz, obligado_contabilidad...)"},"proveedor":{"type":"object","description":"Sujeto retenido: tipo_identificacion (04 RUC, 05 c\u00e9dula, 06 pasaporte), identificacion, razon_social, direccion, correo"},"retenciones":{"type":"array","items":{"type":"object","required":["codigoimpuesto","codigo_retencion","base_imponible","porcentaje_retencion","codigo_documento_sustento","numero_documento_sustento","fecha_documento_sustento"],"properties":{"codigoimpuesto":{"type":"integer","enum":[1,2,6],"description":"1 Renta, 2 IVA, 6 ISD"},"codigo_retencion":{"type":"string","example":"312"},"base_imponible":{"type":"number","example":130.01},"porcentaje_retencion":{"type":"number","example":2},"codigo_documento_sustento":{"type":"string","example":"01","description":"01 factura, 03 liquidaci\u00f3n, etc."},"numero_documento_sustento":{"type":"string","example":"001001000000123","description":"15 d\u00edgitos (estab + punto + secuencial)"},"fecha_documento_sustento":{"type":"string","example":"2026\/09\/16"}}}},"informacion_adicional":{"type":"array","items":{"type":"object","properties":{"nombre":{"type":"string"},"detalle":{"type":"string"}}}}},"example":{"ambiente":1,"emisor":{"razon_social":"MI EMPRESA S.A.","nombre_comercial":"MI EMPRESA","ruc":"0999999999001","codigo_establecimiento":"001","codigo_puntoemision":"001","direccion_matriz":"Quito","direccion_establecimiento":"Quito","obligado_contabilidad":"SI","secuencial":"000000001","fecha_emision":"2026\/09\/16"},"proveedor":{"tipo_identificacion":"04","identificacion":"1790011223001","razon_social":"PROVEEDOR S.A.","direccion":"Quito","correo":"proveedor@ejemplo.com"},"retenciones":[{"codigoimpuesto":1,"codigo_retencion":"312","base_imponible":130.01,"porcentaje_retencion":2,"codigo_documento_sustento":"01","numero_documento_sustento":"001001000000123","fecha_documento_sustento":"2026\/09\/16"},{"codigoimpuesto":2,"codigo_retencion":"2","base_imponible":16.5,"porcentaje_retencion":70,"codigo_documento_sustento":"01","numero_documento_sustento":"001001000000123","fecha_documento_sustento":"2026\/09\/16"}],"informacion_adicional":[{"nombre":"Observacion","detalle":"Retencion de prueba"}]}}}}},"responses":{"200":{"description":"Comprobante registrado (se procesa en segundo plano) o rechazado por validaci\u00f3n","content":{"application\/json":{"schema":{"type":"object","properties":{"creado":{"type":"boolean","example":true},"claveacceso":{"type":"string","example":"1609202601099999999900110010010000000011234567810"},"id_comprobante":{"type":"integer","example":1555},"tipo_comprobante":{"type":"string","example":"07"},"estado":{"type":"string","example":"En procesamiento"},"mensaje":{"type":"string"},"errors":{"type":"array","items":{"type":"string"},"description":"Solo cuando creado = false: motivo(s) exactos"}}}}}},"401":{"description":"API Key inv\u00e1lida"},"402":{"description":"Saldo insuficiente de cr\u00e9ditos (solo ambiente 2)"},"429":{"description":"M\u00e1s de 300 peticiones por minuto"}},"x-codeSamples":[{"lang":"cURL","source":"curl -X POST \"https:\/\/www.invoka.com.ec\/api\/retencion\/emision\" \\\n  -H \"X-API-KEY: tu-api-key\" -H \"Content-Type: application\/json\" \\\n  -d '{\"ambiente\":1,\"emisor\":{\"razon_social\":\"MI EMPRESA S.A.\",\"nombre_comercial\":\"MI EMPRESA\",\"ruc\":\"0999999999001\",\"codigo_establecimiento\":\"001\",\"codigo_puntoemision\":\"001\",\"direccion_matriz\":\"Quito\",\"direccion_establecimiento\":\"Quito\",\"obligado_contabilidad\":\"SI\",\"secuencial\":\"000000001\",\"fecha_emision\":\"2026\/09\/16\"},\"proveedor\":{\"tipo_identificacion\":\"04\",\"identificacion\":\"1790011223001\",\"razon_social\":\"PROVEEDOR S.A.\",\"direccion\":\"Quito\",\"correo\":\"proveedor@ejemplo.com\"},\"retenciones\":[{\"codigoimpuesto\":1,\"codigo_retencion\":\"312\",\"base_imponible\":130.01,\"porcentaje_retencion\":2,\"codigo_documento_sustento\":\"01\",\"numero_documento_sustento\":\"001001000000123\",\"fecha_documento_sustento\":\"2026\/09\/16\"},{\"codigoimpuesto\":2,\"codigo_retencion\":\"2\",\"base_imponible\":16.5,\"porcentaje_retencion\":70,\"codigo_documento_sustento\":\"01\",\"numero_documento_sustento\":\"001001000000123\",\"fecha_documento_sustento\":\"2026\/09\/16\"}],\"informacion_adicional\":[{\"nombre\":\"Observacion\",\"detalle\":\"Retencion de prueba\"}]}'"}],"operationId":"emitir_retencion"}},"\/api\/creditos\/saldo":{"get":{"tags":["Cr\u00e9ditos"],"summary":"Consultar saldo de cr\u00e9ditos","description":"Consulta el saldo de cr\u00e9ditos disponibles del usuario autenticado.\n\n**Informaci\u00f3n retornada:**\n- Cr\u00e9ditos disponibles\n- Estado del saldo (suficiente, bajo, agotado)\n- Datos de la empresa asociada","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Saldo consultado exitosamente","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"creditos_disponibles":{"type":"number","example":5000},"estado_saldo":{"type":"string","example":"suficiente","description":"suficiente, bajo o agotado"}}}}}},"401":{"description":"API Key inv\u00e1lida"},"429":{"description":"M\u00e1s de 300 peticiones por minuto por API key"}},"x-codeSamples":[{"lang":"cURL","source":"curl -X GET \"https:\/\/www.invoka.com.ec\/api\/creditos\/saldo\" \\\n  -H \"X-API-KEY: tu-api-key\""}],"operationId":"consultar_saldo_creditos"}},"\/api\/creditos\/historial":{"get":{"tags":["Cr\u00e9ditos"],"summary":"Historial de transacciones de cr\u00e9ditos","description":"Consulta el historial de consumo y recarga de cr\u00e9ditos.\n\n**Par\u00e1metros opcionales:**\n- `limit`: M\u00e1ximo de registros (default 20, max 100)\n- `page`: P\u00e1gina de resultados\n- `tipo`: Filtrar por tipo (consumo, recarga, rollback)\n- `ambiente`: Filtrar por ambiente (1=desarrollo, 2=producci\u00f3n)","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"tipo","in":"query","schema":{"type":"string","enum":["consumo","recarga","rollback"]}},{"name":"ambiente","in":"query","schema":{"type":"string","enum":["1","2"]}}],"responses":{"200":{"description":"Historial consultado exitosamente"},"401":{"description":"API Key inv\u00e1lida"},"429":{"description":"M\u00e1s de 300 peticiones por minuto por API key"}},"x-codeSamples":[{"lang":"cURL","source":"curl -X GET \"https:\/\/www.invoka.com.ec\/api\/creditos\/historial?limit=20&page=1\" \\\n  -H \"X-API-KEY: tu-api-key\""}],"operationId":"historial_creditos"}},"\/api\/consultaprocesar":{"post":{"tags":["Procesamiento"],"summary":"Consultar y reprocesar comprobante","description":"Webhook para consultar el estado de un comprobante y reprocesarlo si es necesario.\n\n**Uso:** Cuando un comprobante qued\u00f3 en un estado intermedio, este endpoint permite reactivar su procesamiento.\n\n**Flujo:** Busca el comprobante por clave de acceso, verifica su estado y lo reenv\u00eda al motor de procesamiento.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["ruc","idcomprobanteinvoka","claveacceso"],"properties":{"ruc":{"type":"string","description":"RUC de la empresa","example":"0991234567001"},"idcomprobanteinvoka":{"type":"integer","description":"ID interno del comprobante","example":12345},"claveacceso":{"type":"string","description":"Clave de acceso del comprobante (49 d\u00edgitos)","example":"1501202407091234567800110010010000000011234567890"}}}}}},"responses":{"200":{"description":"Resultado del procesamiento","content":{"application\/json":{"schema":{"type":"object","properties":{"creado":{"type":"boolean","example":true},"mensaje":{"type":"string","example":"Comprobante procesado correctamente"}}}}}},"401":{"description":"API Key inv\u00e1lida"},"404":{"description":"Comprobante no encontrado"},"429":{"description":"M\u00e1s de 300 peticiones por minuto por API key"}},"x-codeSamples":[{"lang":"cURL","source":"curl -X POST \"https:\/\/www.invoka.com.ec\/api\/consultaprocesar\" \\\n  -H \"X-API-KEY: tu-api-key\" \\\n  -H \"Content-Type: application\/json\" \\\n  -d '{\"ruc\":\"0991234567001\",\"idcomprobanteinvoka\":12345,\"claveacceso\":\"1501202407091234567800110010010000000011234567890\"}'"}],"operationId":"consultar_procesar_comprobante"}},"\/api\/debito\/emision":{"post":{"tags":["Notas de D\u00e9bito"],"summary":"Emitir nota de d\u00e9bito electr\u00f3nica (c\u00f3digo 05)","description":"Nota de d\u00e9bito 1.0.0 sobre una factura (`documento_modificado`). Cada elemento de `modificaciones` lleva la raz\u00f3n, el valor (base) y `tipo_modificacion` = c\u00f3digo de IVA (0, 2, 4, 5, 6, 7, 8, 10); Invoka calcula los impuestos y el total.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["ambiente","emisor","comprador","documento_modificado","modificaciones"],"properties":{"ambiente":{"type":"integer","example":1},"emisor":{"type":"object","properties":{"razon_social":{"type":"string","example":"MI EMPRESA S.A."},"nombre_comercial":{"type":"string","example":"MI EMPRESA"},"ruc":{"type":"string","example":"0999999999001"},"codigo_establecimiento":{"type":"string","example":"001"},"codigo_puntoemision":{"type":"string","example":"001"},"direccion_matriz":{"type":"string","example":"Quito"},"direccion_establecimiento":{"type":"string","example":"Quito"},"obligado_contabilidad":{"type":"string","example":"NO"},"secuencial":{"type":"string","example":"000000001"},"fecha_emision":{"type":"string","example":"2026\/09\/16"}}},"comprador":{"type":"object","properties":{"tipo_identificacion":{"type":"string","example":"05"},"identificacion":{"type":"string","example":"1710034065"},"razon_social":{"type":"string","example":"CLIENTE DE PRUEBA"},"direccion":{"type":"string","example":"Quito"},"correo":{"type":"string","example":"cliente@ejemplo.com"}}},"documento_modificado":{"type":"object","properties":{"codigo_documento_sustento":{"type":"string","example":"01"},"numero_documento_sustento":{"type":"string","example":"001001000000123"},"fecha_documento_sustento":{"type":"string","example":"2026\/09\/16"}}},"modificaciones":{"type":"array","items":{"type":"object","properties":{"razon_modificacion":{"type":"string","example":"Inter\u00e9s por mora"},"valor_modificacion":{"type":"number","example":2.5},"tipo_modificacion":{"type":"integer","example":4}}}},"pagos":{"type":"array","items":{"type":"object","properties":{"tipo":{"type":"string","example":"01"},"total":{"type":"integer","example":0}}}}},"example":{"ambiente":1,"emisor":{"razon_social":"MI EMPRESA S.A.","nombre_comercial":"MI EMPRESA","ruc":"0999999999001","codigo_establecimiento":"001","codigo_puntoemision":"001","direccion_matriz":"Quito","direccion_establecimiento":"Quito","obligado_contabilidad":"NO","secuencial":"000000001","fecha_emision":"2026\/09\/16"},"comprador":{"tipo_identificacion":"05","identificacion":"1710034065","razon_social":"CLIENTE DE PRUEBA","direccion":"Quito","correo":"cliente@ejemplo.com"},"documento_modificado":{"codigo_documento_sustento":"01","numero_documento_sustento":"001001000000123","fecha_documento_sustento":"2026\/09\/16"},"modificaciones":[{"razon_modificacion":"Inter\u00e9s por mora","valor_modificacion":2.5,"tipo_modificacion":4},{"razon_modificacion":"Gasto de cobranza","valor_modificacion":1.25,"tipo_modificacion":0}],"pagos":[{"tipo":"01","total":0}]}}}}},"responses":{"200":{"description":"Comprobante registrado (se procesa en segundo plano) o rechazado por validaci\u00f3n","content":{"application\/json":{"schema":{"type":"object","properties":{"creado":{"type":"boolean","example":true},"claveacceso":{"type":"string","example":"1609202601099999999900110010010000000011234567810"},"id_comprobante":{"type":"integer","example":1555},"tipo_comprobante":{"type":"string","example":"07"},"estado":{"type":"string","example":"En procesamiento"},"mensaje":{"type":"string"},"errors":{"type":"array","items":{"type":"string"},"description":"Solo cuando creado = false: motivo(s) exactos"}}}}}},"401":{"description":"API Key inv\u00e1lida"},"402":{"description":"Saldo insuficiente de cr\u00e9ditos (solo ambiente 2)"},"429":{"description":"M\u00e1s de 300 peticiones por minuto"}},"x-codeSamples":[{"lang":"cURL","source":"curl -X POST \"https:\/\/www.invoka.com.ec\/api\/debito\/emision\" \\\n  -H \"X-API-KEY: tu-api-key\" -H \"Content-Type: application\/json\" \\\n  -d '{\"ambiente\":1,\"emisor\":{\"razon_social\":\"MI EMPRESA S.A.\",\"nombre_comercial\":\"MI EMPRESA\",\"ruc\":\"0999999999001\",\"codigo_establecimiento\":\"001\",\"codigo_puntoemision\":\"001\",\"direccion_matriz\":\"Quito\",\"direccion_establecimiento\":\"Quito\",\"obligado_contabilidad\":\"NO\",\"secuencial\":\"000000001\",\"fecha_emision\":\"2026\/09\/16\"},\"comprador\":{\"tipo_identificacion\":\"05\",\"identificacion\":\"1710034065\",\"razon_social\":\"CLIENTE DE PRUEBA\",\"direccion\":\"Quito\",\"correo\":\"cliente@ejemplo.com\"},\"documento_modificado\":{\"codigo_documento_sustento\":\"01\",\"numero_documento_sustento\":\"001001000000123\",\"fecha_documento_sustento\":\"2026\/09\/16\"},\"modificaciones\":[{\"razon_modificacion\":\"Inter\u00e9s por mora\",\"valor_modificacion\":2.5,\"tipo_modificacion\":4},{\"razon_modificacion\":\"Gasto de cobranza\",\"valor_modificacion\":1.25,\"tipo_modificacion\":0}],\"pagos\":[{\"tipo\":\"01\",\"total\":0}]}'"}],"operationId":"emitir_nota_debito"}},"\/api\/liquidacion\/emision":{"post":{"tags":["Liquidaciones de Compra"],"summary":"Emitir liquidaci\u00f3n de compra electr\u00f3nica (c\u00f3digo 03)","description":"Liquidaci\u00f3n de compra 1.1.0 a un `proveedor` (mismo formato de `items` que la factura: cantidad, precio_unitario, descuento, tipo_iva).","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["ambiente","emisor","proveedor","items"],"properties":{"ambiente":{"type":"integer","example":1},"emisor":{"type":"object","properties":{"razon_social":{"type":"string","example":"MI EMPRESA S.A."},"nombre_comercial":{"type":"string","example":"MI EMPRESA"},"ruc":{"type":"string","example":"0999999999001"},"codigo_establecimiento":{"type":"string","example":"001"},"codigo_puntoemision":{"type":"string","example":"001"},"direccion_matriz":{"type":"string","example":"Quito"},"direccion_establecimiento":{"type":"string","example":"Quito"},"obligado_contabilidad":{"type":"string","example":"NO"},"secuencial":{"type":"string","example":"000000001"},"fecha_emision":{"type":"string","example":"2026\/09\/16"}}},"proveedor":{"type":"object","properties":{"tipo_identificacion":{"type":"string","example":"05"},"identificacion":{"type":"string","example":"1710034065"},"razon_social":{"type":"string","example":"PROVEEDOR INFORMAL"},"direccion":{"type":"string","example":"Quito"}}},"items":{"type":"array","items":{"type":"object","properties":{"codigo_principal":{"type":"string","example":"S001"},"descripcion":{"type":"string","example":"Servicio de jardiner\u00eda"},"cantidad":{"type":"integer","example":3},"precio_unitario":{"type":"number","example":33.33},"descuento":{"type":"integer","example":0},"tipo_iva":{"type":"integer","example":4}}}},"pagos":{"type":"array","items":{"type":"object","properties":{"tipo":{"type":"string","example":"01"},"total":{"type":"integer","example":0}}}}},"example":{"ambiente":1,"emisor":{"razon_social":"MI EMPRESA S.A.","nombre_comercial":"MI EMPRESA","ruc":"0999999999001","codigo_establecimiento":"001","codigo_puntoemision":"001","direccion_matriz":"Quito","direccion_establecimiento":"Quito","obligado_contabilidad":"NO","secuencial":"000000001","fecha_emision":"2026\/09\/16"},"proveedor":{"tipo_identificacion":"05","identificacion":"1710034065","razon_social":"PROVEEDOR INFORMAL","direccion":"Quito"},"items":[{"codigo_principal":"S001","descripcion":"Servicio de jardiner\u00eda","cantidad":3,"precio_unitario":33.33,"descuento":0,"tipo_iva":4}],"pagos":[{"tipo":"01","total":0}]}}}}},"responses":{"200":{"description":"Comprobante registrado (se procesa en segundo plano) o rechazado por validaci\u00f3n","content":{"application\/json":{"schema":{"type":"object","properties":{"creado":{"type":"boolean","example":true},"claveacceso":{"type":"string","example":"1609202601099999999900110010010000000011234567810"},"id_comprobante":{"type":"integer","example":1555},"tipo_comprobante":{"type":"string","example":"07"},"estado":{"type":"string","example":"En procesamiento"},"mensaje":{"type":"string"},"errors":{"type":"array","items":{"type":"string"},"description":"Solo cuando creado = false: motivo(s) exactos"}}}}}},"401":{"description":"API Key inv\u00e1lida"},"402":{"description":"Saldo insuficiente de cr\u00e9ditos (solo ambiente 2)"},"429":{"description":"M\u00e1s de 300 peticiones por minuto"}},"x-codeSamples":[{"lang":"cURL","source":"curl -X POST \"https:\/\/www.invoka.com.ec\/api\/liquidacion\/emision\" \\\n  -H \"X-API-KEY: tu-api-key\" -H \"Content-Type: application\/json\" \\\n  -d '{\"ambiente\":1,\"emisor\":{\"razon_social\":\"MI EMPRESA S.A.\",\"nombre_comercial\":\"MI EMPRESA\",\"ruc\":\"0999999999001\",\"codigo_establecimiento\":\"001\",\"codigo_puntoemision\":\"001\",\"direccion_matriz\":\"Quito\",\"direccion_establecimiento\":\"Quito\",\"obligado_contabilidad\":\"NO\",\"secuencial\":\"000000001\",\"fecha_emision\":\"2026\/09\/16\"},\"proveedor\":{\"tipo_identificacion\":\"05\",\"identificacion\":\"1710034065\",\"razon_social\":\"PROVEEDOR INFORMAL\",\"direccion\":\"Quito\"},\"items\":[{\"codigo_principal\":\"S001\",\"descripcion\":\"Servicio de jardiner\u00eda\",\"cantidad\":3,\"precio_unitario\":33.33,\"descuento\":0,\"tipo_iva\":4}],\"pagos\":[{\"tipo\":\"01\",\"total\":0}]}'"}],"operationId":"emitir_liquidacion_compra"}},"\/api\/comprobante\/consulta\/{claveacceso}":{"get":{"tags":["Consulta de Comprobantes"],"summary":"Estado de un comprobante (y enlaces a XML\/PDF)","description":"Devuelve el estado actual del comprobante. `autorizado` = true cuando el SRI lo autoriz\u00f3; `requiere_correccion` = true cuando el SRI lo devolvi\u00f3 o rechaz\u00f3 (el motivo exacto viene en `errores`) y hay que emitirlo de nuevo con otro secuencial; `en_proceso` = true mientras se procesa o reintenta.\n\n**Estados**: 0-3 en proceso \u00b7 4 autorizado \u00b7 5 no autorizado \u00b7 6 devuelto por el SRI \u00b7 7\/17 error de firma \u00b7 8\/11 en procesamiento \/ SRI no disponible (se reintenta) \u00b7 15 establecimiento cerrado \u00b7 18 l\u00edmite diario de intentos.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"claveacceso","in":"path","required":true,"schema":{"type":"string","minLength":49,"maxLength":49},"description":"Clave de acceso (49 d\u00edgitos) devuelta al emitir"}],"responses":{"200":{"description":"Estado del comprobante","content":{"application\/json":{"schema":{"type":"object","example":{"creado":true,"claveacceso":"1609202601099999999900110010010000000011234567810","tipo_comprobante":"01","numero":"001-001-000000001","ambiente":1,"fecha_emision":"2026-09-16","estado":4,"estado_texto":"Autorizado","autorizado":true,"en_proceso":false,"requiere_correccion":false,"errores":null,"numero_autorizacion":"1609202601099999999900110010010000000011234567810","fecha_autorizacion":"2026-09-16 13:05:34","pdf_generado":true,"credito_cobrado":false,"xml":"https:\/\/... (URL temporal 24h)","pdf":"https:\/\/... (URL temporal 24h)"}}}}},"404":{"description":"Comprobante no encontrado para esta API key"},"429":{"description":"M\u00e1s de 300 peticiones por minuto por API key"}},"x-codeSamples":[{"lang":"cURL","source":"curl -X GET \"https:\/\/www.invoka.com.ec\/api\/comprobante\/consulta\/1609202601099999999900110010010000000011234567810\" \\\n  -H \"X-API-KEY: tu-api-key\""}],"operationId":"consultar_comprobante"}},"\/api\/comprobante\/xml\/{claveacceso}":{"get":{"tags":["Consulta de Comprobantes"],"summary":"Descargar el XML autorizado","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"claveacceso","in":"path","required":true,"schema":{"type":"string","minLength":49,"maxLength":49},"description":"Clave de acceso (49 d\u00edgitos) devuelta al emitir"}],"responses":{"200":{"description":"XML autorizado (application\/xml)"},"409":{"description":"El comprobante a\u00fan no est\u00e1 autorizado"},"429":{"description":"M\u00e1s de 300 peticiones por minuto por API key"}},"x-codeSamples":[{"lang":"cURL","source":"curl -X GET \"https:\/\/www.invoka.com.ec\/api\/comprobante\/xml\/1609202601099999999900110010010000000011234567810\" \\\n  -H \"X-API-KEY: tu-api-key\""}],"operationId":"descargar_xml_comprobante"}},"\/api\/comprobante\/pdf\/{claveacceso}":{"get":{"tags":["Consulta de Comprobantes"],"summary":"Descargar el PDF (RIDE)","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"claveacceso","in":"path","required":true,"schema":{"type":"string","minLength":49,"maxLength":49},"description":"Clave de acceso (49 d\u00edgitos) devuelta al emitir"}],"responses":{"200":{"description":"PDF (application\/pdf). En ambiente de pruebas lleva marca de agua"},"409":{"description":"El comprobante a\u00fan no est\u00e1 autorizado"},"429":{"description":"M\u00e1s de 300 peticiones por minuto por API key"}},"x-codeSamples":[{"lang":"cURL","source":"curl -X GET \"https:\/\/www.invoka.com.ec\/api\/comprobante\/pdf\/1609202601099999999900110010010000000011234567810\" \\\n  -H \"X-API-KEY: tu-api-key\""}],"operationId":"descargar_pdf_comprobante"}},"\/api\/webhook":{"get":{"tags":["Webhook"],"summary":"Ver la configuraci\u00f3n del webhook y las \u00faltimas entregas","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Configuraci\u00f3n actual","content":{"application\/json":{"schema":{"type":"object","example":{"creado":true,"webhook_url":"https:\/\/tusistema.com\/invoka\/webhook","activo":true,"secret":"a1b2...","eventos":["comprobante.autorizado","comprobante.error"],"ultimas_entregas":[{"evento":"comprobante.autorizado","claveacceso":"1609...","intento":1,"codigo_http":200,"ok":1,"created_at":"2026-09-16 13:05:40"}]}}}}},"429":{"description":"M\u00e1s de 300 peticiones por minuto por API key"}},"x-codeSamples":[{"lang":"cURL","source":"curl -X GET \"https:\/\/www.invoka.com.ec\/api\/webhook\" \\\n  -H \"X-API-KEY: tu-api-key\""}],"operationId":"ver_webhook"},"post":{"tags":["Webhook"],"summary":"Registrar o cambiar el webhook de la cuenta","description":"Invoka hace un **POST JSON** a tu URL cuando un comprobante llega a un estado definitivo:\n\n- `comprobante.autorizado`: el SRI lo autoriz\u00f3 (estado 4 o 9).\n- `comprobante.error`: termin\u00f3 con un error que hay que corregir (devuelto, no autorizado, firma inv\u00e1lida, establecimiento cerrado\u2026).\n\nAs\u00ed no necesitas consultar el estado en bucle. Un solo webhook por cuenta (sirve para todas tus empresas). Tambi\u00e9n acepta `PUT`.\n\n### Cabeceras de cada aviso\n\n| Cabecera | Valor |\n|---|---|\n| `Content-Type` | `application\/json` |\n| `User-Agent` | `Invoka-Webhook\/1.0` |\n| `X-Invoka-Event` | `comprobante.autorizado`, `comprobante.error` o `webhook.prueba` |\n| `X-Invoka-Delivery` | UUID del aviso: **el mismo en todos sus reintentos** (sirve para deduplicar) |\n| `X-Invoka-Signature` | `sha256=` + HMAC-SHA256 en hexadecimal (min\u00fasculas) del **cuerpo crudo** con tu `secret` |\n| `X-Invoka-Timestamp` | Momento del env\u00edo (segundos Unix) |\n| `X-Invoka-Signature-V2` | **Recomendada.** `t=<timestamp>,v1=<HMAC-SHA256 hex de \"<timestamp>.<cuerpo crudo>\" con tu secret>`. Rechaza el aviso si \\|ahora \u2212 t\\| > 300 s: as\u00ed nadie puede reenviarte un aviso viejo. |\n\nLa URL del webhook debe ser **p\u00fablica** (https recomendado): no se aceptan `localhost`, IP privadas ni direcciones internas. El `secret` completo solo se muestra al guardarlo; `GET \/api\/webhook` lo devuelve enmascarado.\n\n### C\u00f3mo verificar la firma\n\nCalcula el HMAC sobre los **bytes exactos** que recibes (no re-serialices el JSON: Invoka lo env\u00eda sin escapar `\/` ni caracteres Unicode) y comp\u00e1ralo en tiempo constante:\n\n```php\n$cuerpo = file_get_contents('php:\/\/input');\n$esperada = 'sha256=' . hash_hmac('sha256', $cuerpo, $secret);\nif (!hash_equals($esperada, $_SERVER['HTTP_X_INVOKA_SIGNATURE'] ?? '')) { http_response_code(401); exit; }\n```\n\n```js\n\/\/ Node \/ Express: app.post('\/invoka\/webhook', express.raw({ type: 'application\/json' }), ...)\nconst crypto = require('crypto');\nconst esperada = 'sha256=' + crypto.createHmac('sha256', secret).update(req.body).digest('hex');\nconst ok = crypto.timingSafeEqual(Buffer.from(esperada), Buffer.from(req.get('X-Invoka-Signature') || ''));\n```\n\n```python\nimport hmac, hashlib\nesperada = 'sha256=' + hmac.new(secret.encode(), request.get_data(), hashlib.sha256).hexdigest()\nok = hmac.compare_digest(esperada, request.headers.get('X-Invoka-Signature', ''))\n```\n\nLa firma no incluye marca de tiempo: si te preocupa la repetici\u00f3n de avisos, guarda `claveacceso` + `evento` y descarta duplicados.\n\n### Cuerpo\n\n`evento`, `claveacceso`, `tipo_comprobante`, `numero` (001-001-000000001), `ambiente`, `ruc_emisor`, `estado`, `estado_texto`, `autorizado`, `requiere_correccion`, `errores` (solo si hay error), `numero_autorizacion`, `fecha_autorizacion`, `xml` y `pdf` (URL de `\/api\/comprobante\/xml|pdf\/{claveacceso}`, que piden tu API key) y `enviado_en` (ISO 8601). Ver *Webhooks* al final de esta documentaci\u00f3n.\n\n### Reintentos\n\nResponde **2xx** en menos de 25 s. Si no, se reintenta: **5 intentos en total** (el primero y 4 reintentos a 1, 5, 15 y 60 minutos). Cada intento queda en `ultimas_entregas` de `GET \/api\/webhook`.\n\nSi no mandas `secret` se conserva el actual o se genera uno de 40 caracteres y se devuelve en la respuesta.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","example":"https:\/\/tusistema.com\/invoka\/webhook"},"secret":{"type":"string","minLength":16,"description":"Opcional: se genera si no lo mandas"},"activo":{"type":"boolean","default":true}}}}}},"responses":{"200":{"description":"Webhook guardado (incluye el secret con el que se firman los avisos)","content":{"application\/json":{"schema":{"type":"object","example":{"creado":true,"webhook_url":"https:\/\/tusistema.com\/invoka\/webhook","activo":true,"secret":"mi-secreto-de-al-menos-16-caracteres","eventos":["comprobante.autorizado","comprobante.error"],"firma":"Cabecera X-Invoka-Signature = sha256=HMAC_SHA256(cuerpo_json, secret)","mensaje":"Webhook guardado. Guarda el secret: con \u00e9l verificas la firma de cada aviso."}}}}},"422":{"description":"URL inv\u00e1lida (debe empezar por http:\/\/ o https:\/\/) o secret de menos de 16 caracteres"},"429":{"description":"M\u00e1s de 300 peticiones por minuto por API key"}},"x-codeSamples":[{"lang":"cURL","source":"curl -X POST \"https:\/\/www.invoka.com.ec\/api\/webhook\" \\\n  -H \"X-API-KEY: tu-api-key\" -H \"Content-Type: application\/json\" \\\n  -d '{\"url\":\"https:\/\/tusistema.com\/invoka\/webhook\",\"secret\":\"mi-secreto-de-al-menos-16-caracteres\"}'"}],"operationId":"guardar_webhook"},"delete":{"tags":["Webhook"],"summary":"Eliminar el webhook","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Eliminado"},"429":{"description":"M\u00e1s de 300 peticiones por minuto por API key"}},"x-codeSamples":[{"lang":"cURL","source":"curl -X DELETE \"https:\/\/www.invoka.com.ec\/api\/webhook\" \\\n  -H \"X-API-KEY: tu-api-key\""}],"operationId":"eliminar_webhook"}},"\/api\/webhook\/probar":{"post":{"tags":["Webhook"],"summary":"Enviar un evento de prueba (webhook.prueba) a tu URL","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Prueba encolada"},"422":{"description":"No hay webhook configurado"},"429":{"description":"M\u00e1s de 300 peticiones por minuto por API key"}},"x-codeSamples":[{"lang":"cURL","source":"curl -X POST \"https:\/\/www.invoka.com.ec\/api\/webhook\/probar\" \\\n  -H \"X-API-KEY: tu-api-key\" -H \"Content-Type: application\/json\" \\\n  -d '[]'"}],"description":"Encola un aviso `webhook.prueba` firmado igual que los reales, con cuerpo `{\"evento\":\"webhook.prueba\",\"mensaje\":\"Prueba de webhook de Invoka\",\"claveacceso\":\"000\u20260 (49 ceros)\",\"enviado_en\":\"\u2026\"}`. El resultado (c\u00f3digo HTTP de tu servidor) aparece en `ultimas_entregas` de `GET \/api\/webhook` a los pocos segundos.","operationId":"probar_webhook"}},"\/api\/comprobante\/reprocesar":{"post":{"tags":["Consulta de Comprobantes"],"summary":"Volver a procesar un comprobante","description":"Reencola un comprobante que qued\u00f3 en un estado temporal (SRI no disponible, en procesamiento) o que ya corregiste en el SRI (por ejemplo, establecimiento cerrado). Un comprobante devuelto por estructura o secuencial repetido no cambia al reprocesar: corrige el JSON y emite uno nuevo.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["claveacceso"],"properties":{"claveacceso":{"type":"string","example":"1609202601099999999900110010010000000011234567810"}},"example":{"claveacceso":"1609202601099999999900110010010000000011234567810"}}}}},"responses":{"200":{"description":"Enviado a reprocesar, ya autorizado o en proceso (ver `mensaje`)"},"429":{"description":"M\u00e1s de 300 peticiones por minuto por API key"}},"x-codeSamples":[{"lang":"cURL","source":"curl -X POST \"https:\/\/www.invoka.com.ec\/api\/comprobante\/reprocesar\" \\\n  -H \"X-API-KEY: tu-api-key\" -H \"Content-Type: application\/json\" \\\n  -d '{\"claveacceso\":\"1609202601099999999900110010010000000011234567810\"}'"}],"operationId":"reprocesar_comprobante"}},"\/api\/sri\/ruc\/{ruc}":{"get":{"tags":["Consultas SRI y Registro Civil"],"summary":"Consultar datos completos de un RUC","description":"Consulta en tiempo real ante el catastro oficial del SRI. Devuelve raz\u00f3n social, tipo de contribuyente (Persona Natural o Jur\u00eddica), r\u00e9gimen (RIMPE, General), estado activo\/pasivo, desglose de nombres, agente de retenci\u00f3n, obligado a llevar contabilidad y listado completo de establecimientos con sus direcciones.\n\n**Tambi\u00e9n**: `POST \/api\/sri\/ruc` con `{\"ruc\": \"\u2026\"}` (o `identificacion`) y el alias `GET \/api\/consulta\/ruc\/{ruc}`.\n\n**Cobro**: dentro de las 20 gratis del mes no cuesta; despu\u00e9s descuenta **1 consulta** de la billetera de consultas por respuesta con datos (`meta.creditos_consultas_cobrados`). Si no hay datos (404) no se cobra.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"ruc","in":"path","required":true,"schema":{"type":"string","example":"1792345678001"},"description":"N\u00famero de RUC (13 d\u00edgitos)"}],"responses":{"200":{"description":"Datos oficiales del contribuyente devueltos por el SRI","content":{"application\/json":{"schema":{"type":"object","example":{"success":true,"data":{"tipo_identificacion":"04","identificacion":"1792345678001","numeroRuc":"1792345678001","razon_social":"PEREZ LOPEZ JUAN CARLOS","razonSocial":"PEREZ LOPEZ JUAN CARLOS","tipo_contribuyente":"PERSONA NATURAL","tipoContribuyente":"PERSONA NATURAL","estado_contribuyente":"ACTIVO","regimen":"GENERAL","categoria":null,"obligado_contabilidad":"NO","obligadoLlevarContabilidad":"NO","agente_retencion":"NO","agenteRetencion":"NO","contribuyente_especial":"NO","contribuyenteEspecial":"NO","actividad_economica":"ACTIVIDADES DE CONSULTORIA EN SOFTWARE Y TECNOLOGIAS DE LA INFORMACION","actividadEconomicaPrincipal":"ACTIVIDADES DE CONSULTORIA EN SOFTWARE Y TECNOLOGIAS DE LA INFORMACION","contribuyente_fantasma":"NO","transacciones_inexistentes":"NO","fechas":{"inicio_actividades":"2015-08-10 00:00:00.0","cese":"","reinicio":"","actualizacion":"2026-05-12 10:15:00.0"},"nombres_desglosados":{"primer_nombre":"JUAN","segundo_nombre":"CARLOS","primer_apellido":"PEREZ","segundo_apellido":"LOPEZ"},"matriz":{"codigo":"001","nombre_comercial":"SOLUCIONES DIGITALES ECUADOR","direccion":"PICHINCHA \/ QUITO \/ I\u00d1AQUITO \/ AV. AMAZONAS N24-100","provincia":"PICHINCHA","ciudad":"QUITO","canton":"I\u00d1AQUITO"},"establecimientos":[{"codigo":"001","nombre_comercial":"SOLUCIONES DIGITALES ECUADOR","tipo_establecimiento":"MATRIZ","estado":"ABIERTO","direccion_completa":"PICHINCHA \/ QUITO \/ I\u00d1AQUITO \/ AV. AMAZONAS N24-100","provincia":"PICHINCHA","ciudad":"QUITO","canton":"I\u00d1AQUITO","direccion":"AV. AMAZONAS N24-100"}]}}}}}},"404":{"description":"El RUC no existe en el catastro del SRI","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"error":"No existe el RUC en los registros del SRI"}}}}},"422":{"description":"Formato de RUC no v\u00e1lido (debe tener 13 d\u00edgitos)","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"error":"El RUC debe contener exactamente 13 d\u00edgitos num\u00e9ricos"}}}}},"402":{"description":"Cupo gratis del mes agotado y billetera de consultas en 0 (`limite_alcanzado: true`)","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"error":"Has alcanzado tus 20 consultas gratuitas de este mes. Tu saldo de consultas adicional es 0. ...","limite_alcanzado":true,"meta":{"consultas_mes":20,"limite_gratis_mes":20,"consultas_gratis_restantes":0}}}}}},"429":{"description":"M\u00e1s de 300 peticiones por minuto por API key"}},"x-codeSamples":[{"lang":"cURL","source":"curl -X GET \"https:\/\/www.invoka.com.ec\/api\/sri\/ruc\/1792345678001\" \\\n  -H \"X-API-KEY: tu-api-key\""}],"operationId":"consultar_ruc"}},"\/api\/sri\/ruc\/{ruc}\/establecimientos":{"get":{"tags":["Consultas SRI y Registro Civil"],"summary":"Consultar \u00fanicamente los establecimientos de un RUC","description":"Devuelve el listado completo y detallado de los establecimientos (matriz y sucursales) registrados ante el SRI para un RUC espec\u00edfico, incluyendo c\u00f3digo (ej. 001, 002), nombre comercial, tipo de establecimiento (MATRIZ, SUCURSAL), estado (ABIERTO, CERRADO) y direcci\u00f3n desglosada.\n\n**Tambi\u00e9n**: `GET \/api\/sri\/establecimientos\/{ruc}`, `POST \/api\/sri\/establecimientos` con `{\"ruc\": \"\u2026\"}` y los alias bajo `\/api\/consulta\/...`.\n\n**Cobro**: dentro de las 20 gratis del mes no cuesta; despu\u00e9s descuenta **1 consulta** de la billetera de consultas por respuesta con datos (`meta.creditos_consultas_cobrados`). Si no hay datos (404) no se cobra.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"ruc","in":"path","required":true,"schema":{"type":"string","example":"1792345678001"},"description":"N\u00famero de RUC (13 d\u00edgitos)"}],"responses":{"200":{"description":"Listado de establecimientos del contribuyente","content":{"application\/json":{"schema":{"type":"object","example":{"success":true,"ruc":"1792345678001","total_establecimientos":2,"establecimientos":[{"codigo":"001","nombre_comercial":"SOLUCIONES DIGITALES MATRIZ","tipo_establecimiento":"MATRIZ","estado":"ABIERTO","direccion_completa":"PICHINCHA \/ QUITO \/ I\u00d1AQUITO \/ AV. AMAZONAS N24-100","provincia":"PICHINCHA","ciudad":"QUITO","canton":"I\u00d1AQUITO","direccion":"AV. AMAZONAS N24-100"},{"codigo":"002","nombre_comercial":"SOLUCIONES DIGITALES SUCURSAL NORTE","tipo_establecimiento":"SUCURSAL","estado":"ABIERTO","direccion_completa":"PICHINCHA \/ QUITO \/ COTOCOLLAO \/ AV. PRENSA N45-12","provincia":"PICHINCHA","ciudad":"QUITO","canton":"COTOCOLLAO","direccion":"AV. PRENSA N45-12"}],"meta":{"consultas_mes":1,"limite_gratis_mes":20,"consultas_gratis_restantes":19,"billetera_consultas_saldo":0,"creditos_consultas_cobrados":0}}}}}},"404":{"description":"No se encontraron establecimientos para el RUC","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"error":"No se pudo obtener la informaci\u00f3n de establecimientos del RUC"}}}}},"422":{"description":"Formato de RUC no v\u00e1lido","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"error":"El RUC debe contener exactamente 13 d\u00edgitos num\u00e9ricos"}}}}},"402":{"description":"Cupo gratis del mes agotado y billetera de consultas en 0 (`limite_alcanzado: true`)","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"error":"Has alcanzado tus 20 consultas gratuitas de este mes. Tu saldo de consultas adicional es 0. ...","limite_alcanzado":true,"meta":{"consultas_mes":20,"limite_gratis_mes":20,"consultas_gratis_restantes":0}}}}}},"429":{"description":"M\u00e1s de 300 peticiones por minuto por API key"}},"x-codeSamples":[{"lang":"cURL","source":"curl -X GET \"https:\/\/www.invoka.com.ec\/api\/sri\/ruc\/1792345678001\/establecimientos\" \\\n  -H \"X-API-KEY: tu-api-key\""}],"operationId":"consultar_establecimientos_ruc"}},"\/api\/sri\/cedula\/{cedula}":{"get":{"tags":["Consultas SRI y Registro Civil"],"summary":"Consultar datos oficiales de una C\u00e9dula","description":"Consulta oficial en tiempo real ante el Registro Civil de Ecuador. Devuelve nombre completo oficial y desglose estructurado en primer nombre, segundo nombre, primer apellido y segundo apellido.\n\n**Tambi\u00e9n**: `POST \/api\/sri\/cedula` con `{\"cedula\": \"\u2026\"}` (o `identificacion`) y el alias `GET \/api\/consulta\/cedula\/{cedula}`.\n\n**Cobro**: dentro de las 20 gratis del mes no cuesta; despu\u00e9s descuenta **1 consulta** de la billetera de consultas por respuesta con datos (`meta.creditos_consultas_cobrados`). Si no hay datos (404) no se cobra.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"cedula","in":"path","required":true,"schema":{"type":"string","example":"1712345678"},"description":"N\u00famero de c\u00e9dula de identidad ecuatoriana (10 d\u00edgitos)"}],"responses":{"200":{"description":"Datos oficiales de la persona natural devueltos por el Registro Civil","content":{"application\/json":{"schema":{"type":"object","example":{"success":true,"data":{"tipo_identificacion":"05","identificacion":"1712345678","cedula":"1712345678","nombre_completo":"PEREZ LOPEZ JUAN CARLOS","razon_social":"PEREZ LOPEZ JUAN CARLOS","tipo_contribuyente":"PERSONA NATURAL","fecha_defuncion":null,"nombres_desglosados":{"primer_nombre":"JUAN","segundo_nombre":"CARLOS","primer_apellido":"PEREZ","segundo_apellido":"LOPEZ"}}}}}}},"404":{"description":"La c\u00e9dula no existe en el Registro Civil","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"error":"No existe la c\u00e9dula en el Registro Civil"}}}}},"422":{"description":"Formato de c\u00e9dula no v\u00e1lido (debe tener 10 d\u00edgitos)","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"error":"La c\u00e9dula debe contener exactamente 10 d\u00edgitos num\u00e9ricos"}}}}},"402":{"description":"Cupo gratis del mes agotado y billetera de consultas en 0 (`limite_alcanzado: true`)","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"error":"Has alcanzado tus 20 consultas gratuitas de este mes. Tu saldo de consultas adicional es 0. ...","limite_alcanzado":true,"meta":{"consultas_mes":20,"limite_gratis_mes":20,"consultas_gratis_restantes":0}}}}}},"429":{"description":"M\u00e1s de 300 peticiones por minuto por API key"}},"x-codeSamples":[{"lang":"cURL","source":"curl -X GET \"https:\/\/www.invoka.com.ec\/api\/sri\/cedula\/1712345678\" \\\n  -H \"X-API-KEY: tu-api-key\""}],"operationId":"consultar_cedula"}},"\/api\/sri\/consulta\/{identificacion}":{"get":{"tags":["Consultas SRI y Registro Civil"],"summary":"Consulta unificada autom\u00e1tica (RUC o C\u00e9dula)","description":"Endpoint universal: detecta autom\u00e1ticamente si la identificaci\u00f3n enviada es una C\u00e9dula (10 d\u00edgitos) o un RUC (13 d\u00edgitos) y consulta la fuente correspondiente (Registro Civil o SRI).\n\n**Tambi\u00e9n**: `POST \/api\/sri\/consulta` con `{\"identificacion\": \"\u2026\"}`.\n\n**Cobro**: dentro de las 20 gratis del mes no cuesta; despu\u00e9s descuenta **1 consulta** de la billetera de consultas por respuesta con datos (`meta.creditos_consultas_cobrados`). Si no hay datos (404) no se cobra.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"identificacion","in":"path","required":true,"schema":{"type":"string","example":"1792345678001"},"description":"C\u00e9dula (10 d\u00edgitos) o RUC (13 d\u00edgitos)"}],"responses":{"200":{"description":"Datos obtenidos exitosamente de la fuente correspondiente","content":{"application\/json":{"schema":{"type":"object","example":{"success":true,"data":{"tipo_identificacion":"04","identificacion":"1792345678001","razon_social":"PEREZ LOPEZ JUAN CARLOS","tipo_contribuyente":"PERSONA NATURAL","estado_contribuyente":"ACTIVO","regimen":"GENERAL","nombres_desglosados":{"primer_nombre":"JUAN","segundo_nombre":"CARLOS","primer_apellido":"PEREZ","segundo_apellido":"LOPEZ"}}}}}}},"404":{"description":"Identificaci\u00f3n no encontrada","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"error":"No existe la identificaci\u00f3n en los registros oficiales"}}}}},"422":{"description":"Identificaci\u00f3n inv\u00e1lida","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"error":"Identificaci\u00f3n inv\u00e1lida: debe ser c\u00e9dula (10 d\u00edgitos) o RUC (13 d\u00edgitos)"}}}}},"402":{"description":"Cupo gratis del mes agotado y billetera de consultas en 0 (`limite_alcanzado: true`)","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"error":"Has alcanzado tus 20 consultas gratuitas de este mes. Tu saldo de consultas adicional es 0. ...","limite_alcanzado":true,"meta":{"consultas_mes":20,"limite_gratis_mes":20,"consultas_gratis_restantes":0}}}}}},"429":{"description":"M\u00e1s de 300 peticiones por minuto por API key"}},"x-codeSamples":[{"lang":"cURL","source":"curl -X GET \"https:\/\/www.invoka.com.ec\/api\/sri\/consulta\/1792345678001\" \\\n  -H \"X-API-KEY: tu-api-key\""}],"operationId":"consultar_identificacion"}},"\/api\/sri\/razon-social\/{texto}":{"get":{"tags":["Consultas SRI y Registro Civil"],"summary":"B\u00fasqueda de contribuyentes por Raz\u00f3n Social o Nombre Comercial","description":"B\u00fasqueda oficial en tiempo real ante el catastro del SRI por coincidencia de texto en la raz\u00f3n social o nombre comercial (m\u00ednimo 3 caracteres). Devuelve el total de coincidencias y el listado de contribuyentes con su RUC, estado, r\u00e9gimen, tipo de contribuyente y actividad econ\u00f3mica.\n\n**Incluye 20 consultas gratuitas al mes por cuenta**. Solo se descuenta del cupo si se obtienen datos exitosamente.\n\n**Tambi\u00e9n**: `POST \/api\/sri\/razon-social` con `{\"razon_social\": \"\u2026\", \"limite\": 20}` (tambi\u00e9n `nombre` o `criterio`) y el alias `GET \/api\/consulta\/razon-social\/{texto}`.\n\n**Cobro**: dentro de las 20 gratis del mes no cuesta; despu\u00e9s descuenta **1 consulta** de la billetera de consultas por respuesta con datos (`meta.creditos_consultas_cobrados`). Si no hay datos (404) no se cobra.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"texto","in":"path","required":true,"schema":{"type":"string","example":"FERRETERIA"},"description":"Texto a buscar (m\u00ednimo 3 caracteres)"},{"name":"limite","in":"query","required":false,"schema":{"type":"integer","default":20},"description":"Cantidad m\u00e1xima de resultados detallados (1 a 50)"}],"responses":{"200":{"description":"Listado de contribuyentes encontrados en el SRI","content":{"application\/json":{"schema":{"type":"object","example":{"success":true,"criterio":"FERRETERIA","total_encontrados":20,"mostrados":2,"data":[{"numeroRuc":"0990000000001","identificacion":"0990000000001","razonSocial":"FERRETERIA EJEMPLO CIA. LTDA.","razon_social":"FERRETERIA EJEMPLO CIA. LTDA.","estado":"ACTIVO","tipo_contribuyente":"SOCIEDAD","regimen":"GENERAL","categoria":null,"obligado_contabilidad":"SI","agente_retencion":"NO","contribuyente_especial":"NO","actividad_economica":"VENTA AL POR MAYOR DE ART\u00cdCULOS DE FERRETER\u00cdA","representantes_legales":[{"identificacion":"0900000000","nombre":"PEREZ LOPEZ JUAN CARLOS"}]},{"numeroRuc":"1790000000001","identificacion":"1790000000001","razonSocial":"FERRETERIA DEMO S.A.","razon_social":"FERRETERIA DEMO S.A.","estado":"PASIVO","tipo_contribuyente":"SOCIEDAD","regimen":"GENERAL","categoria":null,"obligado_contabilidad":"SI","agente_retencion":"NO","contribuyente_especial":"NO","actividad_economica":"VENTA AL POR MENOR DE ART\u00cdCULOS DE FERRETER\u00cdA"}],"meta":{"consultas_mes":1,"limite_gratis_mes":20,"consultas_gratis_restantes":19,"billetera_consultas_saldo":0,"creditos_consultas_cobrados":0}}}}}},"404":{"description":"No se encontraron resultados para la raz\u00f3n social ingresada","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"error":"La b\u00fasqueda no gener\u00f3 resultados en los registros del SRI","criterio":"FERRETERIA INEXISTENTE XYZ","total_encontrados":0}}}}},"422":{"description":"Criterio de b\u00fasqueda inv\u00e1lido","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"error":"El criterio de b\u00fasqueda debe tener al menos 3 caracteres"}}}}},"402":{"description":"Cupo gratis del mes agotado y billetera de consultas en 0 (`limite_alcanzado: true`)","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"error":"Has alcanzado tus 20 consultas gratuitas de este mes. Tu saldo de consultas adicional es 0. ...","limite_alcanzado":true,"meta":{"consultas_mes":20,"limite_gratis_mes":20,"consultas_gratis_restantes":0}}}}}},"429":{"description":"M\u00e1s de 300 peticiones por minuto por API key"}},"x-codeSamples":[{"lang":"cURL","source":"curl -X GET \"https:\/\/www.invoka.com.ec\/api\/sri\/razon-social\/FERRETERIA\" \\\n  -H \"X-API-KEY: tu-api-key\""}],"operationId":"buscar_razon_social"}},"\/api\/status":{"get":{"tags":["Estado y precios"],"summary":"Estado de los servicios de Invoka","security":[],"description":"P\u00fablico, sin API key. `overall_status` es `operational`, `degraded` o `major_outage`; cada servicio trae su estado y tiempo de respuesta. P\u00e1gina humana: https:\/\/www.invoka.com.ec\/estado.","responses":{"200":{"description":"Estado actual","content":{"application\/json":{"schema":{"type":"object","example":{"overall_status":"operational","services":[{"id":1,"name":"API REST","slug":"api-rest","status":"operational","status_label":"Operacional","uptime_percentage":100,"response_time_ms":null,"updated_at":"2026-10-02T14:32:29.000000Z"},{"id":2,"name":"Procesamiento SRI","slug":"procesamiento-sri","status":"operational","status_label":"Operacional","uptime_percentage":100,"response_time_ms":974,"updated_at":"2026-10-02T14:32:29.000000Z"}],"active_incidents":[],"checked_at":"2026-10-02T09:32:29-05:00"}}}}},"429":{"description":"M\u00e1s de 300 peticiones por minuto por API key"}},"x-codeSamples":[{"lang":"cURL","source":"curl -X GET \"https:\/\/www.invoka.com.ec\/api\/status\""}],"operationId":"estado_servicio"}},"\/api\/public\/pricing\/tiers":{"get":{"tags":["Estado y precios"],"summary":"Planes de precios de cr\u00e9ditos de facturaci\u00f3n","security":[],"description":"P\u00fablico, sin API key. Tramos por monto de recarga con el precio por comprobante con y sin IVA.","responses":{"200":{"description":"Tramos activos","content":{"application\/json":{"schema":{"type":"object","example":{"success":true,"iva_percentage":15,"data":[{"id":10,"name":"STARTER","description":"Para comenzar","min_amount":"50.00","max_amount":"299.99","price_per_credit":"0.0250","price_per_credit_with_iva":"0.0287","iva_percentage":15,"discount_percentage":0,"formatted_price_range":"$50.00 - $299.99","credit_range":{"min":1742,"max":10452},"examples":{"min_credits":1742,"example_amount":"50.00","example_credits":1742}}]}}}}},"429":{"description":"M\u00e1s de 300 peticiones por minuto por API key"}},"x-codeSamples":[{"lang":"cURL","source":"curl -X GET \"https:\/\/www.invoka.com.ec\/api\/public\/pricing\/tiers\""}],"operationId":"listar_planes_precios"}},"\/api\/public\/pricing\/calculate":{"get":{"tags":["Estado y precios"],"summary":"Calcular cu\u00e1ntos cr\u00e9ditos da un monto","security":[],"description":"P\u00fablico, sin API key. `amount` es el valor a pagar **con IVA** (USD).","parameters":[{"name":"amount","in":"query","required":true,"schema":{"type":"number","example":100},"description":"Monto en USD con IVA"}],"responses":{"200":{"description":"Cr\u00e9ditos que corresponden al monto","content":{"application\/json":{"schema":{"type":"object","example":{"success":true,"data":{"amount":"100","subtotal":86.96,"iva_percentage":15,"iva_amount":13.04,"credits":3484,"tier":{"id":10,"name":"STARTER","description":"Para comenzar","price_per_credit":"0.0250","price_per_credit_with_iva":"0.0287","discount_percentage":0},"savings":null}}}}}},"422":{"description":"Falta `amount` o no es num\u00e9rico"},"429":{"description":"M\u00e1s de 300 peticiones por minuto por API key"}},"x-codeSamples":[{"lang":"cURL","source":"curl -X GET \"https:\/\/www.invoka.com.ec\/api\/public\/pricing\/calculate?amount=100\""}],"operationId":"calcular_creditos_por_monto"}},"\/api\/comprobante\/consulta":{"get":{"tags":["Consulta de Comprobantes"],"summary":"Estado de un comprobante (clave en la query)","security":[{"ApiKeyAuth":[]}],"description":"Igual que `GET \/api\/comprobante\/consulta\/{claveacceso}`, con la clave en el par\u00e1metro `?claveacceso=`. `xml` y `pdf` son enlaces firmados de S3 v\u00e1lidos 24 h (o la URL de la API si no est\u00e1n en S3) y solo vienen cuando `autorizado` es true.","parameters":[{"name":"claveacceso","in":"query","required":true,"schema":{"type":"string","minLength":49,"maxLength":49,"example":"0210202601095107267700110010010000000011234567811"}}],"responses":{"200":{"description":"Estado del comprobante","content":{"application\/json":{"schema":{"type":"object","example":{"creado":true,"claveacceso":"0210202601095107267700110010010000000011234567811","tipo_comprobante":"01","numero":"001-001-000000001","ambiente":1,"fecha_emision":"2026-10-02","estado":4,"estado_texto":"Autorizado","autorizado":true,"en_proceso":false,"requiere_correccion":false,"errores":null,"numero_autorizacion":"0210202601095107267700110010010000000011234567811","fecha_autorizacion":"2026-10-02 10:15:03","pdf_generado":true,"correo_enviado":true,"credito_cobrado":false,"xml":"https:\/\/\u2026amazonaws.com\/\u2026xml?X-Amz-Expires=86400\u2026","pdf":"https:\/\/\u2026amazonaws.com\/\u2026pdf?X-Amz-Expires=86400\u2026"}}}}},"401":{"description":"API Key ausente o inv\u00e1lida"},"404":{"description":"No existe un comprobante con esa clave emitido con tu API key","content":{"application\/json":{"schema":{"type":"object","example":{"creado":false,"errors":["Comprobante no encontrado para esta API key"]}}}}},"422":{"description":"Clave de acceso con largo distinto de 49","content":{"application\/json":{"schema":{"type":"object","example":{"creado":false,"errors":["claveacceso debe tener 49 digitos"]}}}}},"429":{"description":"M\u00e1s de 300 peticiones por minuto por API key"}},"x-codeSamples":[{"lang":"cURL","source":"curl -X GET \"https:\/\/www.invoka.com.ec\/api\/comprobante\/consulta?claveacceso=0210202601095107267700110010010000000011234567811\" \\\n  -H \"X-API-KEY: tu-api-key\""}],"operationId":"consultar_comprobante_por_query"},"post":{"tags":["Consulta de Comprobantes"],"summary":"Estado de un comprobante (clave en el cuerpo)","security":[{"ApiKeyAuth":[]}],"description":"Igual que `GET \/api\/comprobante\/consulta\/{claveacceso}`, con la clave en el cuerpo JSON. `xml` y `pdf` son enlaces firmados de S3 v\u00e1lidos 24 h (o la URL de la API si no est\u00e1n en S3) y solo vienen cuando `autorizado` es true.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["claveacceso"],"properties":{"claveacceso":{"type":"string","minLength":49,"maxLength":49,"example":"0210202601095107267700110010010000000011234567811"}}}}}},"responses":{"200":{"description":"Estado del comprobante","content":{"application\/json":{"schema":{"type":"object","example":{"creado":true,"claveacceso":"0210202601095107267700110010010000000011234567811","tipo_comprobante":"01","numero":"001-001-000000001","ambiente":1,"fecha_emision":"2026-10-02","estado":4,"estado_texto":"Autorizado","autorizado":true,"en_proceso":false,"requiere_correccion":false,"errores":null,"numero_autorizacion":"0210202601095107267700110010010000000011234567811","fecha_autorizacion":"2026-10-02 10:15:03","pdf_generado":true,"correo_enviado":true,"credito_cobrado":false,"xml":"https:\/\/\u2026amazonaws.com\/\u2026xml?X-Amz-Expires=86400\u2026","pdf":"https:\/\/\u2026amazonaws.com\/\u2026pdf?X-Amz-Expires=86400\u2026"}}}}},"401":{"description":"API Key ausente o inv\u00e1lida"},"404":{"description":"No existe un comprobante con esa clave emitido con tu API key","content":{"application\/json":{"schema":{"type":"object","example":{"creado":false,"errors":["Comprobante no encontrado para esta API key"]}}}}},"422":{"description":"Clave de acceso con largo distinto de 49","content":{"application\/json":{"schema":{"type":"object","example":{"creado":false,"errors":["claveacceso debe tener 49 digitos"]}}}}},"429":{"description":"M\u00e1s de 300 peticiones por minuto por API key"}},"x-codeSamples":[{"lang":"cURL","source":"curl -X POST \"https:\/\/www.invoka.com.ec\/api\/comprobante\/consulta\" \\\n  -H \"X-API-KEY: tu-api-key\" \\\n  -H \"Content-Type: application\/json\" \\\n  -d '{\"claveacceso\":\"0210202601095107267700110010010000000011234567811\"}'"}],"operationId":"consultar_comprobante_por_cuerpo"}},"\/api\/id\/verificaciones":{"post":{"tags":["Invoka ID"],"summary":"[Beta privada] Crear una verificaci\u00f3n de identidad (enlace para el usuario)","security":[{"ApiKeyAuth":[]}],"description":"Crea una sesi\u00f3n y devuelve `url_verificacion`: env\u00edala a tu usuario para que haga la captura desde su celular. El resultado llega a `webhook_url` (evento `id.verificacion.finalizada`) y se consulta con `GET \/api\/id\/verificaciones\/{id}`.\n\n**Tiene costo** seg\u00fan `tipo`: `prueba_de_vida` $0.50, `cedula_ocr` $0.75, `completa` $1.00 (+ IVA). `cedula_esperada` que no tenga 10 d\u00edgitos se ignora.","requestBody":{"required":false,"content":{"application\/json":{"schema":{"type":"object","properties":{"tipo":{"type":"string","enum":["prueba_de_vida","cedula_ocr","completa"],"default":"completa"},"cedula_esperada":{"type":"string","maxLength":15,"example":"0900000000","description":"Si la env\u00edas, la c\u00e9dula le\u00edda debe coincidir"},"webhook_url":{"type":"string","format":"uri","maxLength":255,"description":"Por defecto, la URL del webhook de tu cuenta"},"tiempo_expiracion_minutos":{"type":"integer","minimum":5,"maximum":1440,"default":30},"metadatos":{"type":"object","description":"Datos tuyos que se devuelven tal cual","example":{"cliente_id":"abc-123"}}}}}}},"responses":{"201":{"description":"Verificaci\u00f3n creada","content":{"application\/json":{"schema":{"type":"object","example":{"success":true,"id":"verif_k3j9x0a1b2c3d4e5","tipo":"completa","estado":"pendiente","costo":1,"url_verificacion":"https:\/\/www.invoka.com.ec\/id\/v\/AbCdEf0123456789AbCdEf0123456789AbCdEf01","token":"AbCdEf0123456789AbCdEf0123456789AbCdEf01","cedula_esperada":"0900000000","expira_en":"2026-10-02T10:45:00-05:00","metadatos":{"cliente_id":"abc-123"}}}}}},"401":{"description":"API Key ausente o inv\u00e1lida"},"422":{"description":"Datos inv\u00e1lidos (tipo, URL, minutos fuera de 5\u20131440)"},"429":{"description":"M\u00e1s de 300 peticiones por minuto por API key"}},"x-codeSamples":[{"lang":"cURL","source":"curl -X POST \"https:\/\/www.invoka.com.ec\/api\/id\/verificaciones\" \\\n  -H \"X-API-KEY: tu-api-key\" \\\n  -H \"Content-Type: application\/json\" \\\n  -d '{\"tipo\":\"completa\",\"cedula_esperada\":\"0900000000\",\"webhook_url\":\"https:\/\/tusistema.com\/invoka\/id\",\"metadatos\":{\"cliente_id\":\"abc-123\"}}'"}],"operationId":"crear_verificacion_identidad"},"get":{"tags":["Invoka ID"],"summary":"[Beta privada] Listar mis verificaciones","security":[{"ApiKeyAuth":[]}],"description":"Paginado de 15 en 15, de la m\u00e1s reciente a la m\u00e1s antigua.","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1}}],"responses":{"200":{"description":"Listado","content":{"application\/json":{"schema":{"type":"object","example":{"success":true,"data":[{"uuid":"verif_k3j9x0a1b2c3d4e5","tipo":"completa","estado":"aprobado","score_confianza":"91.50","costo":"1.00","created_at":"2026-10-02T15:00:00.000000Z"}],"meta":{"total":1,"pagina_actual":1,"por_pagina":15,"ultima_pagina":1}}}}}},"429":{"description":"M\u00e1s de 300 peticiones por minuto por API key"}},"x-codeSamples":[{"lang":"cURL","source":"curl -X GET \"https:\/\/www.invoka.com.ec\/api\/id\/verificaciones?page=1\" \\\n  -H \"X-API-KEY: tu-api-key\""}],"operationId":"listar_verificaciones_identidad"}},"\/api\/id\/verificaciones\/{id}":{"get":{"tags":["Invoka ID"],"summary":"[Beta privada] Consultar el resultado de una verificaci\u00f3n","security":[{"ApiKeyAuth":[]}],"description":"`estado`: `pendiente`, `aprobado`, `rechazado` o `expirado`. Sin costo.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"verif_k3j9x0a1b2c3d4e5"},"description":"`id` (uuid) devuelto al crear"}],"responses":{"200":{"description":"Resultado","content":{"application\/json":{"schema":{"type":"object","example":{"success":true,"id":"verif_k3j9x0a1b2c3d4e5","tipo":"completa","estado":"aprobado","score_confianza":91.5,"prueba_de_vida":{"resultado":true,"score":92,"detalles":[]},"documento":{"cedula":"0900000000"},"biometria":{"match_score":94.2,"aprobado":true},"dispositivo":[],"reporte_url":"https:\/\/www.invoka.com.ec\/id\/v\/TOKEN\/reporte","expira_en":"2026-10-02T10:45:00-05:00","completado_en":"2026-10-02T10:20:00-05:00","created_at":"2026-10-02T10:15:00-05:00"}}}}},"404":{"description":"No existe o no es de tu cuenta","content":{"application\/json":{"schema":{"type":"object","example":{"success":false,"error":"Verificaci\u00f3n no encontrada."}}}}},"429":{"description":"M\u00e1s de 300 peticiones por minuto por API key"}},"x-codeSamples":[{"lang":"cURL","source":"curl -X GET \"https:\/\/www.invoka.com.ec\/api\/id\/verificaciones\/verif_k3j9x0a1b2c3d4e5\" \\\n  -H \"X-API-KEY: tu-api-key\""}],"operationId":"consultar_verificacion_identidad"}},"\/api\/id\/verificar-directo":{"post":{"tags":["Invoka ID"],"summary":"[Beta privada] Verificar identidad directamente (im\u00e1genes en base64)","security":[{"ApiKeyAuth":[]}],"description":"Para cuando t\u00fa ya capturaste las im\u00e1genes: crea la verificaci\u00f3n y la procesa en la misma llamada. Im\u00e1genes como data URI base64 (`data:image\/jpeg;base64,...`). `selfie` es obligatoria salvo que env\u00edes `cedula_frontal`.\n\n**Tiene costo** seg\u00fan `tipo` (igual que crear una verificaci\u00f3n).","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"tipo":{"type":"string","enum":["prueba_de_vida","cedula_ocr","completa"],"default":"completa"},"selfie":{"type":"string","description":"Base64 de la selfie"},"cedula_frontal":{"type":"string","description":"Base64 del anverso de la c\u00e9dula"},"cedula_reverso":{"type":"string","description":"Base64 del reverso"},"cedula_numero":{"type":"string","maxLength":15},"nombres":{"type":"string","maxLength":100},"webhook_url":{"type":"string","format":"uri"},"metadatos":{"type":"object"}}}}}},"responses":{"200":{"description":"Resultado","content":{"application\/json":{"schema":{"type":"object","example":{"success":true,"id":"verif_k3j9x0a1b2c3d4e5","estado":"aprobado","score_confianza":91.5,"razones_rechazo":[],"documento":{"cedula":"0900000000"},"prueba_de_vida":{"resultado":true,"score":"92.00"},"biometria":{"match_score":94.2,"aprobado":true},"reporte_url":"https:\/\/www.invoka.com.ec\/id\/v\/TOKEN\/reporte"}}}}},"422":{"description":"Falta `selfie` y `cedula_frontal`, o datos inv\u00e1lidos"},"429":{"description":"M\u00e1s de 300 peticiones por minuto por API key"}},"x-codeSamples":[{"lang":"cURL","source":"curl -X POST \"https:\/\/www.invoka.com.ec\/api\/id\/verificar-directo\" \\\n  -H \"X-API-KEY: tu-api-key\" \\\n  -H \"Content-Type: application\/json\" \\\n  -d '{\"tipo\":\"completa\",\"selfie\":\"data:image\/jpeg;base64,\/9j\/4AAQ...\",\"cedula_frontal\":\"data:image\/jpeg;base64,\/9j\/4AAQ...\",\"cedula_numero\":\"0900000000\"}'"}],"operationId":"verificar_identidad_directo"}}},"x-webhooks":{"comprobante.autorizado":{"post":{"operationId":"webhook_comprobante_autorizado","summary":"comprobante.autorizado","description":"El SRI autoriz\u00f3 el comprobante. `xml` y `pdf` apuntan a la API (env\u00eda tu X-API-KEY para descargarlos).","tags":["Webhook"],"parameters":[{"name":"X-Invoka-Event","in":"header","required":true,"schema":{"type":"string"},"description":"Nombre del evento"},{"name":"X-Invoka-Signature","in":"header","required":true,"schema":{"type":"string","example":"sha256=5d41402abc4b2a76b9719d911017c592..."},"description":"`sha256=` + HMAC-SHA256 (hex) del cuerpo crudo con el `secret` de tu webhook"},{"name":"X-Invoka-Delivery","in":"header","required":true,"schema":{"type":"string","format":"uuid"},"description":"Identificador del intento de entrega"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","example":{"evento":"comprobante.autorizado","claveacceso":"0210202601095107267700110010010000000011234567811","tipo_comprobante":"01","numero":"001-001-000000001","ambiente":1,"ruc_emisor":"0951072677001","estado":4,"estado_texto":"Autorizado","autorizado":true,"requiere_correccion":false,"errores":null,"numero_autorizacion":"0210202601095107267700110010010000000011234567811","fecha_autorizacion":"2026-10-02 10:15:03","xml":"https:\/\/www.invoka.com.ec\/api\/comprobante\/xml\/0210202601095107267700110010010000000011234567811","pdf":"https:\/\/www.invoka.com.ec\/api\/comprobante\/pdf\/0210202601095107267700110010010000000011234567811","enviado_en":"2026-10-02T10:15:05-05:00"}}}}},"responses":{"200":{"description":"Recibido. Cualquier 2xx detiene los reintentos"},"500":{"description":"Cualquier otra respuesta (o m\u00e1s de 25 s) se reintenta hasta 5 intentos en total"}}}},"comprobante.error":{"post":{"operationId":"webhook_comprobante_error","summary":"comprobante.error","description":"El comprobante termin\u00f3 con un error definitivo (estados 5, 6, 7, 15, 17, 18 y similares). Corrige seg\u00fan `errores` y emite uno nuevo con otro secuencial.","tags":["Webhook"],"parameters":[{"name":"X-Invoka-Event","in":"header","required":true,"schema":{"type":"string"},"description":"Nombre del evento"},{"name":"X-Invoka-Signature","in":"header","required":true,"schema":{"type":"string","example":"sha256=5d41402abc4b2a76b9719d911017c592..."},"description":"`sha256=` + HMAC-SHA256 (hex) del cuerpo crudo con el `secret` de tu webhook"},{"name":"X-Invoka-Delivery","in":"header","required":true,"schema":{"type":"string","format":"uuid"},"description":"Identificador del intento de entrega"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","example":{"evento":"comprobante.error","claveacceso":"0210202601095107267700110010010000000011234567811","tipo_comprobante":"01","numero":"001-001-000000001","ambiente":1,"ruc_emisor":"0951072677001","estado":6,"estado_texto":"Devuelto por el SRI (revise el detalle en errores)","autorizado":false,"requiere_correccion":true,"errores":"ERROR SECUENCIAL REGISTRADO","numero_autorizacion":null,"fecha_autorizacion":null,"xml":null,"pdf":null,"enviado_en":"2026-10-02T10:15:05-05:00"}}}}},"responses":{"200":{"description":"Recibido. Cualquier 2xx detiene los reintentos"},"500":{"description":"Cualquier otra respuesta (o m\u00e1s de 25 s) se reintenta hasta 5 intentos en total"}}}},"webhook.prueba":{"post":{"operationId":"webhook_webhook_prueba","summary":"webhook.prueba","description":"Lo env\u00eda `POST \/api\/webhook\/probar` (o el bot\u00f3n del panel). Firmado igual que los reales.","tags":["Webhook"],"parameters":[{"name":"X-Invoka-Event","in":"header","required":true,"schema":{"type":"string"},"description":"Nombre del evento"},{"name":"X-Invoka-Signature","in":"header","required":true,"schema":{"type":"string","example":"sha256=5d41402abc4b2a76b9719d911017c592..."},"description":"`sha256=` + HMAC-SHA256 (hex) del cuerpo crudo con el `secret` de tu webhook"},{"name":"X-Invoka-Delivery","in":"header","required":true,"schema":{"type":"string","format":"uuid"},"description":"Identificador del intento de entrega"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","example":{"evento":"webhook.prueba","mensaje":"Prueba de webhook de Invoka","claveacceso":"0000000000000000000000000000000000000000000000000","enviado_en":"2026-10-02T10:15:05-05:00"}}}}},"responses":{"200":{"description":"Recibido. Cualquier 2xx detiene los reintentos"},"500":{"description":"Cualquier otra respuesta (o m\u00e1s de 25 s) se reintenta hasta 5 intentos en total"}}}},"id.verificacion.finalizada":{"post":{"operationId":"webhook_id_verificacion_finalizada","summary":"id.verificacion.finalizada (Invoka ID)","tags":["Invoka ID"],"description":"Al terminar una verificaci\u00f3n de Invoka ID se hace un POST JSON a la `webhook_url` de la verificaci\u00f3n (o, si no se indic\u00f3, a la del webhook de la cuenta).\n\n**Diferencias con el webhook de comprobantes**: lleva `X-Invoka-Event: id.verificacion.finalizada` y `User-Agent: Invoka-ID-Webhook\/1.0`, pero **no lleva `X-Invoka-Signature`** ni reintentos (un solo intento, 5 s de espera). Conf\u00edrmalo siempre con `GET \/api\/id\/verificaciones\/{id}` antes de actuar.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","example":{"evento":"id.verificacion.finalizada","uuid":"verif_k3j9x0a1b2c3d4e5","tipo":"completa","estado":"aprobado","score_confianza":91.5,"documento":{"cedula":"0900000000"},"biometria":{"match_score":94.2,"aprobado":true},"liveness":{"resultado":true,"score":92},"dispositivo":[],"metadatos":{"cliente_id":"abc-123"},"reporte_url":"https:\/\/www.invoka.com.ec\/id\/v\/TOKEN\/reporte","timestamp":"2026-10-02T10:15:05-05:00"}}}}},"responses":{"200":{"description":"Recibido"}}}}}}