{ "info": { "name": "Contadeo API", "description": "Flujos esenciales de la API de Contadeo (facturación electrónica SRI, Ecuador): onboarding, catálogos, emisión con polling y descargas, cuenta y webhooks.\n\nAutenticación: pon tu API key (`cdo_...`) o un JWT de `/auth/login` en la variable `token` de la colección. Crea la key en el panel: Configuración → API.\n\nRecomendado: prueba primero con `ambienteActivo: 1` (Pruebas del SRI, no gasta cupo). Guía completa: https://contadeo.com/desarrolladores · Matriz de capacidades: https://contadeo.com/capacidades", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "auth": { "type": "bearer", "bearer": [{ "key": "token", "value": "{{token}}", "type": "string" }] }, "variable": [ { "key": "base_url", "value": "https://contadeo.com/api", "type": "string" }, { "key": "token", "value": "", "type": "string", "description": "API key cdo_... (recomendada) o accessToken JWT" }, { "key": "emisorId", "value": "", "type": "string" }, { "key": "establecimientoId", "value": "", "type": "string" }, { "key": "certificadoId", "value": "", "type": "string" }, { "key": "comprobanteId", "value": "", "type": "string" } ], "item": [ { "name": "Onboarding", "item": [ { "name": "Crear cuenta (plan free)", "request": { "method": "POST", "auth": { "type": "noauth" }, "header": [{ "key": "Content-Type", "value": "application/json" }], "url": { "raw": "{{base_url}}/tenants/register", "host": ["{{base_url}}"], "path": ["tenants", "register"] }, "body": { "mode": "raw", "raw": "{\"nombre\":\"Mi Empresa\",\"email\":\"yo@empresa.ec\",\"password\":\"secreta123\",\"slug\":\"mi-empresa\",\"aceptaPrivacidad\":true,\"aceptaTerminos\":true}", "options": { "raw": { "language": "json" } } }, "description": "Alta self-serve: crea la cuenta y el usuario owner en plan free (10 comprobantes/mes). Devuelve accessToken y refreshToken. Público, con rate-limit por IP." } }, { "name": "Iniciar sesión (JWT)", "request": { "method": "POST", "auth": { "type": "noauth" }, "header": [{ "key": "Content-Type", "value": "application/json" }], "url": { "raw": "{{base_url}}/auth/login", "host": ["{{base_url}}"], "path": ["auth", "login"] }, "body": { "mode": "raw", "raw": "{\"email\":\"yo@empresa.ec\",\"password\":\"secreta123\"}", "options": { "raw": { "language": "json" } } }, "description": "Flujo del panel: access token de 15 min + refresh de 7 días. Para integraciones de sistemas usa mejor una API key (no expira)." } }, { "name": "Crear emisor (RUC)", "request": { "method": "POST", "header": [{ "key": "Content-Type", "value": "application/json" }], "url": { "raw": "{{base_url}}/emisores", "host": ["{{base_url}}"], "path": ["emisores"] }, "body": { "mode": "raw", "raw": "{\"ruc\":\"0912345675001\",\"razonSocial\":\"MI EMPRESA S.A.\",\"dirMatriz\":\"Av. Principal 123, Guayaquil\",\"obligadoContabilidad\":false,\"regimen\":\"GENERAL\"}", "options": { "raw": { "language": "json" } } }, "description": "El RUC se valida (dígito verificador). regimen: GENERAL | RIMPE_EMPRENDEDOR | RIMPE_NEGOCIO_POPULAR. Guarda el id devuelto en la variable emisorId." } }, { "name": "Crear establecimiento", "request": { "method": "POST", "header": [{ "key": "Content-Type", "value": "application/json" }], "url": { "raw": "{{base_url}}/emisores/:emisorId/establecimientos", "host": ["{{base_url}}"], "path": ["emisores", ":emisorId", "establecimientos"], "variable": [{ "key": "emisorId", "value": "{{emisorId}}" }] }, "body": { "mode": "raw", "raw": "{\"codigo\":\"001\",\"direccion\":\"Matriz centro\",\"nombre\":\"Matriz\"}", "options": { "raw": { "language": "json" } } }, "description": "codigo: exactamente 3 dígitos. Guarda el id devuelto en establecimientoId." } }, { "name": "Crear punto de emisión", "request": { "method": "POST", "header": [{ "key": "Content-Type", "value": "application/json" }], "url": { "raw": "{{base_url}}/establecimientos/:establecimientoId/puntos-emision", "host": ["{{base_url}}"], "path": ["establecimientos", ":establecimientoId", "puntos-emision"], "variable": [{ "key": "establecimientoId", "value": "{{establecimientoId}}" }] }, "body": { "mode": "raw", "raw": "{\"codigo\":\"001\",\"nombre\":\"Caja 1\"}", "options": { "raw": { "language": "json" } } }, "description": "codigo: 3 dígitos. Con emisor + establecimiento + punto ya se puede emitir." } }, { "name": "Subir certificado de firma (.p12)", "request": { "method": "POST", "header": [{ "key": "Content-Type", "value": "application/json" }], "url": { "raw": "{{base_url}}/certificados", "host": ["{{base_url}}"], "path": ["certificados"] }, "body": { "mode": "raw", "raw": "{\"emisorId\":\"{{emisorId}}\",\"p12Base64\":\"\",\"passphrase\":\"\",\"alias\":\"firma 2026\"}", "options": { "raw": { "language": "json" } } }, "description": "El .p12 y su contraseña se cifran (envelope AES-256-GCM) y solo se descifran en memoria al firmar. Guarda el id devuelto en certificadoId. Genera el base64 con: base64 -w0 certificado.p12" } } ] }, { "name": "Catálogos", "item": [ { "name": "Listar clientes", "request": { "method": "GET", "url": { "raw": "{{base_url}}/clientes?q=&limit=50", "host": ["{{base_url}}"], "path": ["clientes"], "query": [{ "key": "q", "value": "" }, { "key": "limit", "value": "50" }] }, "description": "q busca por razón social, identificación o email. Envía siempre limit (máx. 200) desde integraciones." } }, { "name": "Crear cliente", "request": { "method": "POST", "header": [{ "key": "Content-Type", "value": "application/json" }], "url": { "raw": "{{base_url}}/clientes", "host": ["{{base_url}}"], "path": ["clientes"] }, "body": { "mode": "raw", "raw": "{\"tipoIdentificacion\":\"05\",\"identificacion\":\"1745678902\",\"razonSocial\":\"JUAN PEREZ\",\"email\":\"juan@correo.com\"}", "options": { "raw": { "language": "json" } } }, "description": "tipoIdentificacion + identificacion son únicos por cuenta (409 si ya existe). Con email, el RIDE llega solo al autorizarse." } }, { "name": "Prellenar comprador por RUC/cédula", "request": { "method": "GET", "url": { "raw": "{{base_url}}/clientes/lookup/:identificacion?tipo=04", "host": ["{{base_url}}"], "path": ["clientes", "lookup", ":identificacion"], "query": [{ "key": "tipo", "value": "04" }], "variable": [{ "key": "identificacion", "value": "1790016919001" }] }, "description": "Busca primero en tu directorio y luego en el catastro público del SRI (razón social, dirección, régimen, advertencias). tipo=04 RUC, tipo=05 cédula." } }, { "name": "Validar RUC (catastro SRI)", "request": { "method": "GET", "url": { "raw": "{{base_url}}/sri/ruc/:ruc", "host": ["{{base_url}}"], "path": ["sri", "ruc", ":ruc"], "variable": [{ "key": "ruc", "value": "1790016919001" }] }, "description": "Siempre 200 con veredicto: valido (estructura y dígito verificador), encontrado (catastro), régimen, obligadoContabilidad, agenteRetencion, contribuyenteEspecial y advertencias. Si el SRI se cae, responde con la última copia (fuente: cache, degradado: true)." } }, { "name": "Listar productos", "request": { "method": "GET", "url": { "raw": "{{base_url}}/productos?limit=50", "host": ["{{base_url}}"], "path": ["productos"], "query": [{ "key": "limit", "value": "50" }] }, "description": "Catálogo de ítems facturables de la cuenta." } }, { "name": "Crear producto", "request": { "method": "POST", "header": [{ "key": "Content-Type", "value": "application/json" }], "url": { "raw": "{{base_url}}/productos", "host": ["{{base_url}}"], "path": ["productos"] }, "body": { "mode": "raw", "raw": "{\"codigoPrincipal\":\"SERV-001\",\"nombre\":\"Hora de consultoría\",\"precioUnitario\":75,\"tarifaCodigo\":\"4\"}", "options": { "raw": { "language": "json" } } }, "description": "codigoPrincipal único por cuenta. tarifaCodigo: 4 = IVA 15%, 0 = 0%, 7 = exento, 6 = no objeto." } }, { "name": "Catálogos oficiales del SRI", "request": { "method": "GET", "url": { "raw": "{{base_url}}/sri/catalogos", "host": ["{{base_url}}"], "path": ["sri", "catalogos"] }, "description": "Tarifas de IVA vigentes, formas de pago y tipos de identificación/comprobante con los que valida el backend. Consúmelos en vez de hardcodearlos." } } ] }, { "name": "Emisión", "item": [ { "name": "Emitir factura (202)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "pedido-8841", "description": "Tu identificador (p. ej. el ID del pedido): reintentar con la misma key devuelve el MISMO comprobante" } ], "url": { "raw": "{{base_url}}/comprobantes/factura", "host": ["{{base_url}}"], "path": ["comprobantes", "factura"] }, "body": { "mode": "raw", "raw": "{\"emisorId\":\"{{emisorId}}\",\"certificadoId\":\"{{certificadoId}}\",\"establecimiento\":\"001\",\"puntoEmision\":\"001\",\"infoFactura\":{\"tipoIdentificacionComprador\":\"05\",\"razonSocialComprador\":\"JUAN PEREZ\",\"identificacionComprador\":\"1745678902\",\"obligadoContabilidad\":\"NO\",\"totalSinImpuestos\":10,\"totalDescuento\":0,\"totalConImpuestos\":[{\"codigo\":\"2\",\"codigoPorcentaje\":\"4\",\"baseImponible\":10,\"tarifa\":15,\"valor\":1.5}],\"importeTotal\":11.5,\"pagos\":[{\"formaPago\":\"01\",\"total\":11.5}]},\"detalles\":[{\"descripcion\":\"Producto\",\"cantidad\":1,\"precioUnitario\":10,\"descuento\":0,\"precioTotalSinImpuesto\":10,\"impuestos\":[{\"codigo\":\"2\",\"codigoPorcentaje\":\"4\",\"tarifa\":15,\"baseImponible\":10,\"valor\":1.5}]}]}", "options": { "raw": { "language": "json" } } }, "description": "Asíncrona: responde 202 con {comprobanteId, claveAcceso, estado: BORRADOR}. La fechaEmision la fija el servidor en hora de Ecuador. Guarda comprobanteId y haz polling." } }, { "name": "Consultar comprobante (polling)", "request": { "method": "GET", "url": { "raw": "{{base_url}}/comprobantes/:id", "host": ["{{base_url}}"], "path": ["comprobantes", ":id"], "variable": [{ "key": "id", "value": "{{comprobanteId}}" }] }, "description": "Cada ~3 s hasta estado terminal (AUTORIZADO, RECHAZADO, DEVUELTA). El SRI suele resolver en 5-30 s. En DEVUELTA/RECHAZADO llega mensajesSri con el motivo literal." } }, { "name": "Descargar RIDE (PDF)", "request": { "method": "GET", "url": { "raw": "{{base_url}}/comprobantes/:id/ride", "host": ["{{base_url}}"], "path": ["comprobantes", ":id", "ride"], "variable": [{ "key": "id", "value": "{{comprobanteId}}" }] }, "description": "Devuelve {url}: una URL prefirmada que expira en 1 hora. Descarga el PDF desde esa URL." } }, { "name": "Descargar XML autorizado", "request": { "method": "GET", "url": { "raw": "{{base_url}}/comprobantes/:id/xml", "host": ["{{base_url}}"], "path": ["comprobantes", ":id", "xml"], "variable": [{ "key": "id", "value": "{{comprobanteId}}" }] }, "description": "Igual que el RIDE: URL prefirmada de 1 hora con el XML autorizado por el SRI." } }, { "name": "Emitir nota de crédito", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "nc-pedido-8841" } ], "url": { "raw": "{{base_url}}/comprobantes/nota-credito", "host": ["{{base_url}}"], "path": ["comprobantes", "nota-credito"] }, "body": { "mode": "raw", "raw": "{\"emisorId\":\"{{emisorId}}\",\"certificadoId\":\"{{certificadoId}}\",\"establecimiento\":\"001\",\"puntoEmision\":\"001\",\"infoNotaCredito\":{\"tipoIdentificacionComprador\":\"05\",\"razonSocialComprador\":\"JUAN PEREZ\",\"identificacionComprador\":\"1745678902\",\"obligadoContabilidad\":\"NO\",\"codDocModificado\":\"01\",\"numDocModificado\":\"001-001-000000001\",\"fechaEmisionDocSustento\":\"2026-06-01\",\"totalSinImpuestos\":10,\"valorModificacion\":11.5,\"totalConImpuestos\":[{\"codigo\":\"2\",\"codigoPorcentaje\":\"4\",\"baseImponible\":10,\"valor\":1.5}],\"motivo\":\"Devolución de mercadería\"},\"detalles\":[{\"descripcion\":\"Producto\",\"cantidad\":1,\"precioUnitario\":10,\"descuento\":0,\"precioTotalSinImpuesto\":10,\"impuestos\":[{\"codigo\":\"2\",\"codigoPorcentaje\":\"4\",\"tarifa\":15,\"baseImponible\":10,\"valor\":1.5}]}]}", "options": { "raw": { "language": "json" } } }, "description": "Referencia el documento modificado (codDocModificado, numDocModificado, fechaEmisionDocSustento). Cuerpos de los demás tipos (03, 05, 06, 07): https://contadeo.com/desarrolladores" } }, { "name": "Emitir lote (hasta 100)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "lote-2026-08-28", "description": "La clave de cada elemento se deriva como header:indice; reintentar el lote no duplica" } ], "url": { "raw": "{{base_url}}/comprobantes/lote", "host": ["{{base_url}}"], "path": ["comprobantes", "lote"] }, "body": { "mode": "raw", "raw": "{\"facturas\":[{\"emisorId\":\"{{emisorId}}\",\"certificadoId\":\"{{certificadoId}}\",\"establecimiento\":\"001\",\"puntoEmision\":\"001\",\"infoFactura\":{\"tipoIdentificacionComprador\":\"07\",\"razonSocialComprador\":\"CONSUMIDOR FINAL\",\"identificacionComprador\":\"9999999999999\",\"obligadoContabilidad\":\"NO\",\"totalSinImpuestos\":10,\"totalDescuento\":0,\"totalConImpuestos\":[{\"codigo\":\"2\",\"codigoPorcentaje\":\"4\",\"baseImponible\":10,\"tarifa\":15,\"valor\":1.5}],\"importeTotal\":11.5,\"pagos\":[{\"formaPago\":\"01\",\"total\":11.5}]},\"detalles\":[{\"descripcion\":\"Producto\",\"cantidad\":1,\"precioUnitario\":10,\"descuento\":0,\"precioTotalSinImpuesto\":10,\"impuestos\":[{\"codigo\":\"2\",\"codigoPorcentaje\":\"4\",\"tarifa\":15,\"baseImponible\":10,\"valor\":1.5}]}]}]}", "options": { "raw": { "language": "json" } } }, "description": "Semántica parcial: las válidas se encolan y las inválidas se reportan con su índice. Un 402 (cupo agotado) o 403 detiene el lote y el resto queda NO_INTENTADA; reintentar el MISMO lote es seguro (la Idempotency-Key deriva header:indice). Límite: 10 lotes/min, body 2 MB." } }, { "name": "Anular comprobante", "request": { "method": "POST", "url": { "raw": "{{base_url}}/comprobantes/:id/anular", "host": ["{{base_url}}"], "path": ["comprobantes", ":id", "anular"], "variable": [{ "key": "id", "value": "{{comprobanteId}}" }] }, "description": "Solo sobre AUTORIZADO, hasta el día 7 del mes siguiente y nunca a consumidor final (Resolución 017/2026). Marca el estado interno ANULADO; el trámite formal se hace en SRI en línea." } }, { "name": "Listar comprobantes", "request": { "method": "GET", "url": { "raw": "{{base_url}}/comprobantes?estado=AUTORIZADO&limit=20", "host": ["{{base_url}}"], "path": ["comprobantes"], "query": [{ "key": "estado", "value": "AUTORIZADO" }, { "key": "limit", "value": "20" }] }, "description": "Filtra por estado, emisor y fechas. Devuelve solo el ambiente activo (nunca mezcla Pruebas y Producción)." } } ] }, { "name": "Cuenta", "item": [ { "name": "Uso del plan", "request": { "method": "GET", "url": { "raw": "{{base_url}}/tenants/current/uso-plan", "host": ["{{base_url}}"], "path": ["tenants", "current", "uso-plan"] }, "description": "El plan que rige la emisión y su consumo: límite mensual, usados este mes (Producción y Pruebas por separado), tipos permitidos." } }, { "name": "Cambiar a Producción", "request": { "method": "PATCH", "header": [{ "key": "Content-Type", "value": "application/json" }], "url": { "raw": "{{base_url}}/tenants/current", "host": ["{{base_url}}"], "path": ["tenants", "current"] }, "body": { "mode": "raw", "raw": "{\"ambienteActivo\":2}", "options": { "raw": { "language": "json" } } }, "description": "1 = Pruebas, 2 = Producción. En Producción los comprobantes tienen validez tributaria real: certifica antes cada tipo en Pruebas." } }, { "name": "Cotizar volumen (público)", "request": { "method": "GET", "auth": { "type": "noauth" }, "url": { "raw": "{{base_url}}/pagos/cotizar?comprobantes=3000", "host": ["{{base_url}}"], "path": ["pagos", "cotizar"], "query": [{ "key": "comprobantes", "value": "3000" }] }, "description": "Cotizador público (sin token): qué plan conviene para N comprobantes al mes." } } ] }, { "name": "Webhooks", "item": [ { "name": "Registrar webhook", "request": { "method": "POST", "header": [{ "key": "Content-Type", "value": "application/json" }], "url": { "raw": "{{base_url}}/webhooks", "host": ["{{base_url}}"], "path": ["webhooks"] }, "body": { "mode": "raw", "raw": "{\"url\":\"https://miapp.ec/webhooks/contadeo\",\"eventos\":[\"comprobante.autorizado\",\"comprobante.rechazado\",\"comprobante.devuelto\"],\"descripcion\":\"ERP principal\"}", "options": { "raw": { "language": "json" } } }, "description": "El secret (whsec_...) viaja SOLO en esta respuesta: guárdalo. Cada entrega llega firmada con X-Contadeo-Signature (HMAC-SHA256 sobre timestamp.cuerpo). Solo HTTPS; máx. 5 endpoints." } }, { "name": "Listar webhooks", "request": { "method": "GET", "url": { "raw": "{{base_url}}/webhooks", "host": ["{{base_url}}"], "path": ["webhooks"] }, "description": "Endpoints registrados de la cuenta (sin secretos)." } }, { "name": "Bitácora de entregas", "request": { "method": "GET", "url": { "raw": "{{base_url}}/webhooks/entregas?limit=20", "host": ["{{base_url}}"], "path": ["webhooks", "entregas"], "query": [{ "key": "limit", "value": "20" }] }, "description": "Estado, intentos, código HTTP y último error de cada entrega. Reintentos: 8 con backoff exponencial." } } ] } ] }