Quickstart Boletas de honorarios

Este quickstart muestra el flujo minimo para operar Boletas de honorarios en el sandbox usando OAuth2 client_credentials.

1) Obtener un cliente OAuth

• Scope recomendado: boletas.emit (emision), boletas.cancel (anulacion), boletas.read (consultas).
• Audience sugerida para terceros: https://api.uat.aveniocloud.com.
• Solicita un client_id y client_secret al equipo de soporte o usa el cliente sandbox publico (cuotas limitadas). Para ambientes productivos recomendamos emitir uno por integracion.

2) Pedir token client_credentials

API_BASE="https://api.uat.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 comun):

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

3) Emitir boleta

• Requiere header Idempotency-Key (UUID) por operacion.
• Usa Authorization: Bearer <accessToken>.

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",
    "esClaveUnica": false,
    "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.uat.aveniocloud.com/api/v1/bhe/operaciones/8a1c6c75-8c12-4c74-a1c2-9fb5f7c23c10",
    "callbackRegistered": true
  },
  "traceId": "f6b0..."
}

4) Consultar estado o recibir webhook

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

La respuesta incluye status (pending|processing|completed|failed) y, si esta completa, result.pdfUrl con firma temporal.

5) Anular boleta

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",
    "esClaveUnica": false,
    "folio": 123,
    "causa": 1,
    "callbackUrl": "https://webhook.site/<id>"
  }'

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.