Guía de integración de las APIs AvenioCloud

Este portal reúne los contratos OpenAPI, las guías y los ejemplos necesarios para validar una integración con AvenioCloud en sandbox antes de preparar su paso a producción.

Sandbox activo

Base URL: https://api.sandbox.aveniocloud.com. Solicita credenciales a integraciones@aveniocloud.com para probar con límites controlados.

Paso a producción

Antes de usar una API en producción, confirma credenciales, cuotas, soporte y condiciones aplicables a tu integración con ventas@aveniocloud.com.

Detalle de servicios

Dominio	Estado	Qué resuelve
Auth API	Disponible	Tokens OAuth2 client_credentials con scopes por dominio.
Boletas de honorarios	Disponible	Emisión, anulación, PDF, operaciones asíncronas y reintentos.
Trazabilidad	Disponible	traceId, X-Correlation-Id e idempotencia para diagnosticar operaciones.
Emisión de DTEs	En preparación	Su documentación se publicará cuando el contrato API esté disponible.

Requisitos rápidos

Checklist mínimo para comenzar a probar en sandbox:

• client_id y client_secret emitidos por AvenioCloud.
• URL base sandbox: https://api.sandbox.aveniocloud.com.
• Scopes mínimos para el dominio que integrarás, por ejemplo boletas.read o boletas.emit.
• Identificador de compañía cuando aplique: X-Avenio-Company-Id.

Header o parámetro	Uso
Authorization: Bearer <token>	Token OAuth2 para consumir APIs protegidas.
X-Avenio-Authorization: <token>	Header alternativo usado por algunos flujos existentes.
Idempotency-Key	UUID por operación para evitar duplicados en reintentos.
X-Correlation-Id	UUID no vacío en formato N (32 hex) o D (con guiones), para trazabilidad end-to-end.
scope	Alcances solicitados al invocar Auth API.

Seguridad y buenas prácticas

• Usa scopes mínimos por dominio y rota credenciales ante cualquier sospecha.
• Evita compartir client_secret en repositorios o logs.
• Usa Idempotency-Key en endpoints transaccionales para reintentos seguros.
• Registra traceId y X-Correlation-Id en tus sistemas de monitoreo.
• Envía un solo X-Correlation-Id. AvenioCloud lo normaliza a formato N minúscula; si falta, es inválido o llega repetido, lo reemplaza por un UUID seguro y devuelve el valor efectivo en la respuesta.
• No uses emails, RUT, JWT, bearer tokens, secretos ni datos de negocio como identificador de correlación.

Trazabilidad y soporte

Todas las respuestas incluyen un traceId. Si necesitas ayuda, comparte ese identificador junto con fecha, endpoint, ambiente y el X-Correlation-Id efectivo devuelto por AvenioCloud.

Sandbox vs producción

• Las credenciales de sandbox son de prueba; no las uses en tu ambiente productivo.
• El sandbox tiene límites por client_id; contáctanos si necesitas ampliar cuotas.
• Las cuotas y condiciones de producción dependen del dominio y del caso de uso.
• Antes de activar producción, valida credenciales, soporte y condiciones operativas.

Contacto

Equipo	Correo	Cuándo escribir
Integraciones API	integraciones@aveniocloud.com	Credenciales sandbox, aumento de límites, dudas técnicas o bugs.
Contacto comercial	ventas@aveniocloud.com	Condiciones de producción, volumen esperado o nuevas necesidades de integración.