Saltar al contenido principal

Quickstart Boletas de honorarios

Esta guía cubre todos los endpoints públicos de Boletas de honorarios y cómo invocarlos en sandbox usando OAuth2 client_credentials.

1) Obtener un cliente OAuth​

  • Scopes recomendados según uso:
    • boletas.emit: emisión estándar.
    • boletas.emit.auth-user: emisión por terceros autorizados.
    • boletas.cancel: anulaciones.
    • boletas.operations.read: consulta de operaciones.
    • boletas.operations.retry: reintentos.
    • boletas.authorizations.read: listado de autorizados.
  • Audience sugerida: https://api.sandbox.aveniocloud.com.
  • Solicita client_id y client_secret al equipo de soporte o usa el cliente sandbox público (cuotas limitadas).

2) Pedir token client_credentials​

API_BASE="https://api.sandbox.aveniocloud.com"
CLIENT_ID="<tu_client_id>"
CLIENT_SECRET="<tu_client_secret>"
SCOPES="boletas.emit boletas.cancel"

curl -X POST "$API_BASE/api/v1/connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" \
  -d "scope=$SCOPES"

Respuesta (envelope común):

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOi...",
    "expiresIn": 3600,
    "scope": "boletas.emit boletas.cancel"
  },
  "traceId": "f6b0..."
}

3) Headers comunes​

  • Authorization: Bearer <accessToken>
  • X-Avenio-Company-Id (opcional): GUID de la compañía. Si no se envía, se usa el claim companyId del token.
  • Idempotency-Key (requerido) en endpoints de emisión/anulación/PDF.

4) Endpoints públicos (función + invocación)​

4.1) Emitir boleta​

POST /api/v1/bhe/emitir

Emite una boleta de honorarios con el RUT del usuario autenticado. Flujo asíncrono.

Campos requeridos: rutUsuario, passwordSII, retencion, fechaEmision, emisor, receptor.

TOKEN="<token>"
IDEMPOTENCY="8e8a7d12-4d1e-4b10-bc90-5b4413422222"

curl -X POST "$API_BASE/api/v1/bhe/emitir" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY" \
  -d '{
    "rutUsuario": "11111111-1",
    "passwordSII": "clave-sii-prueba",
    "retencion": "receptor",
    "fechaEmision": "2024-10-20",
    "emisor": { "direccion": "Av. Demo 123" },
    "receptor": {
      "rut": "22222222-2",
      "nombre": "Cliente Demo",
      "direccion": "Calle 123",
      "region": 13,
      "comuna": 13114
    },
    "prestaciones": [
      { "detalle": "Servicio tributario", "valor": 100000 }
    ],
    "callbackUrl": "https://webhook.site/<id>"
  }'

Respuesta 202 Accepted:

{
  "success": true,
  "data": {
    "operationId": "8a1c6c75-8c12-4c74-a1c2-9fb5f7c23c10",
    "status": "pending",
    "statusUrl": "https://api.sandbox.aveniocloud.com/api/v1/bhe/operaciones/8a1c6c75-8c12-4c74-a1c2-9fb5f7c23c10",
    "callbackRegistered": true
  },
  "traceId": "f6b0..."
}

4.2) Emitir boleta como tercero autorizado​

POST /api/v1/bhe/terceros/emitir

Emite una boleta en nombre de un contribuyente que autorizó al usuario autenticado. Flujo asíncrono.

Requiere scope boletas.emit.auth-user.

Campos requeridos: rutUsuario, rutUsuarioAutorizado, passwordSII, retencion, fechaEmision, receptor.

TOKEN="<token>"

curl -X POST "$API_BASE/api/v1/bhe/terceros/emitir" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rutUsuario": "11111111-1",
    "rutUsuarioAutorizado": "33333333-3",
    "passwordSII": "clave-sii-prueba",
    "retencion": "receptor",
    "fechaEmision": "2024-10-20",
    "receptor": {
      "rut": "22222222-2",
      "nombre": "Cliente Demo",
      "direccion": "Calle 123",
      "region": 13,
      "comuna": 13114
    },
    "prestaciones": [
      { "detalle": "Servicio autorizado", "valor": 75000 }
    ],
    "callbackUrl": "https://webhook.site/<id>"
  }'

4.3) Listar contribuyentes autorizados​

POST /api/v1/bhe/terceros/autorizados

Lista contribuyentes que autorizaron al RUT autenticado para emisión por terceros.

Campos requeridos: rutUsuario, passwordSII.

TOKEN="<token>"

curl -X POST "$API_BASE/api/v1/bhe/terceros/autorizados" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rutUsuario": "11111111-1",
    "passwordSII": "clave-sii-prueba"
  }'

4.4) Listar direcciones del emisor​

POST /api/v1/bhe/emisor/direcciones

Obtiene direcciones registradas del emisor según SII.

Campos requeridos: rutUsuario, passwordSII.

TOKEN="<token>"

curl -X POST "$API_BASE/api/v1/bhe/emisor/direcciones" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rutUsuario": "11111111-1",
    "passwordSII": "clave-sii-prueba"
  }'

4.5) Consultar estado de operación o recibir webhook​

GET /api/v1/bhe/operaciones/{operationId}

Consulta el estado de una operación. Estados: pending, processing, completed, failed.

TOKEN="<token>"

curl -X GET "$API_BASE/api/v1/bhe/operaciones/<operationId>" \
  -H "Authorization: Bearer $TOKEN"

La respuesta incluye status y, si está completa, result.pdfUrl con firma temporal.

4.6) Listar operaciones (paginado)​

GET /api/v1/bhe/operaciones

Parámetros útiles:

  • Statuses: pending, processing, completed, failed
  • OperationType: emision, anulacion, consulta_emitida
  • Page, PageSize
TOKEN="<token>"

curl -X GET "$API_BASE/api/v1/bhe/operaciones?Statuses=completed&OperationType=emision&Page=1&PageSize=20" \
  -H "Authorization: Bearer $TOKEN"

4.7) Reintentar operación​

POST /api/v1/bhe/operaciones/{operationId}/retry

Reintenta una operación pendiente o fallida. Flujo asíncrono.

TOKEN="<token>"

curl -X POST "$API_BASE/api/v1/bhe/operaciones/<operationId>/retry" \
  -H "Authorization: Bearer $TOKEN"

4.8) Anular boleta​

POST /api/v1/bhe/anular

Anula una boleta de honorarios (flujo tradicional). Flujo asíncrono.

Campos requeridos: rutUsuario, passwordSII.

TOKEN="<token>"
IDEMPOTENCY="8e8a7d12-4d1e-4b10-bc90-5b4413422222"

curl -X POST "$API_BASE/api/v1/bhe/anular" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY" \
  -d '{
    "rutUsuario": "11111111-1",
    "passwordSII": "clave-sii-prueba",
    "folio": 123,
    "causa": 1,
    "callbackUrl": "https://webhook.site/<id>"
  }'

4.9) Obtener PDF de boleta emitida​

POST /api/v1/bhe/pdf/emitida

Recupera el PDF de una boleta emitida (consulta emitida). Flujo asíncrono.

Campos requeridos: rutUsuario, passwordSII.

TOKEN="<token>"
IDEMPOTENCY="8e8a7d12-4d1e-4b10-bc90-5b4413422222"

curl -X POST "$API_BASE/api/v1/bhe/pdf/emitida" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY" \
  -d '{
    "rutUsuario": "11111111-1",
    "passwordSII": "clave-sii-prueba",
    "folio": 123,
    "anio": 2024,
    "mes": 10
  }'

5) Buenas practicas​

  • Usa un Idempotency-Key unico por operacion para evitar duplicados.
  • Solicita scopes minimos necesarios.
  • Propaga X-Correlation-Id en tus llamados subsecuentes para trazabilidad.
  • Configura callbackUrl sobre HTTPS; recomendamos firmar webhooks con secretos compartidos.
Última actualización en