Boletas de honorarios en sandbox

Esta guía explica los principales flujos publicados de Boletas de honorarios y cómo invocarlos en sandbox mediante OAuth2 client_credentials.

API transaccional

Los endpoints de emisión, anulación y PDF están diseñados para integraciones con trazabilidad, idempotencia y consumo medido. El retry público permanece suspendido según la sección 4.7.

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: reservado para retry; la operación pública está temporalmente suspendida.
- boletas.authorizations.read: listado de autorizados.
Audience sugerida: https://api.sandbox.aveniocloud.com.
Solicita client_id y client_secret al equipo de integraciones. Las credenciales se entregan con scopes y cuotas acotados.

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/auth/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>
Todos los endpoints públicos requieren un token client_credentials con organization_id y company_id firmados. La API comprueba que la compañía pertenezca a la organización antes de consultar o mutar datos.
X-Avenio-Company-Id (opcional): GUID de la compañía. Si se envía, debe coincidir exactamente con company_id; el header no permite cambiar de empresa o tenant.
Idempotency-Key (requerido) en endpoints de emisión/anulación/PDF.
X-Correlation-Id (opcional): un único UUID no vacío N o D. Se normaliza a N minúscula; valores inválidos o múltiples son reemplazados y el valor efectivo se devuelve en la respuesta.

4. Endpoints públicos

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.

La operación se busca sólo dentro de la compañía ligada al token. Un UUID ajeno y uno inexistente retornan el mismo 404 canónico, sin URLs firmadas ni metadatos de la operación.

La superficie pública tenant-scoped se sirve mediante Avenio.Api, que valida la membresía mediante Catalog. El host standalone de Boletas no se publica como superficie pública; si se inicia sin ese verificador, falla cerrado con 403 y no accede a operaciones ni acepta sólo los claims como prueba de membresía.

Si Catalog no puede verificar temporalmente la membresía, la API falla cerrado con 503 Service Unavailable, código canónico DEPENDENCY_FAILURE y traceId. No consulta ni modifica operaciones; en emisión, anulación y recuperación de PDF reintenta con backoff usando el mismo identificador de idempotencia cuando corresponda.

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

El listado siempre queda restringido a la compañía ligada al token; X-Avenio-Company-Id no puede ampliar ese alcance.

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

El reintento automático está temporalmente suspendido hasta que KAN-187 implemente reconciliación e idempotencia seguras. Después de validar autenticación, scope y membresía de compañía, este endpoint retorna 409 Conflict con código OPERATION_FAILED, de manera uniforme para cualquier operationId y estado.

Mientras esté suspendido no consulta ni modifica la operación, no encola trabajo y no contacta al SII. No automatices reintentos sobre esta respuesta.

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 prácticas

Usa un Idempotency-Key único por operación para evitar duplicados.
Solicita scopes mínimos necesarios.
Propaga el X-Correlation-Id efectivo devuelto por la API; nunca uses emails, RUT, JWT, bearer tokens ni datos de negocio como correlación.
Configura callbackUrl sobre HTTPS; recomendamos firmar webhooks con secretos compartidos.

Paso a producción

Cuando tengas el flujo validado en sandbox, coordina credenciales, cuotas, soporte y condiciones de producción con ventas@aveniocloud.com.

1. Obtener un cliente OAuth​

2. Pedir token client_credentials​

3. Headers comunes​

4. Endpoints públicos​

4.1) Emitir boleta​

4.2) Emitir boleta como tercero autorizado​

4.3) Listar contribuyentes autorizados​

4.4) Listar direcciones del emisor​

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

4.6) Listar operaciones (paginado)​

4.7) Reintentar operación​

4.8) Anular boleta​

4.9) Obtener PDF de boleta emitida​

5. Buenas prácticas​

1. Obtener un cliente OAuth

2. Pedir token `client_credentials`

3. Headers comunes

4. Endpoints públicos

4.1) Emitir boleta

4.2) Emitir boleta como tercero autorizado

4.3) Listar contribuyentes autorizados

4.4) Listar direcciones del emisor

4.5) Consultar estado de operación o recibir webhook

4.6) Listar operaciones (paginado)

4.7) Reintentar operación

4.8) Anular boleta

4.9) Obtener PDF de boleta emitida

5. Buenas prácticas