Notta Docs

API: BHE

Boleta de Honorarios Electrónica con retención de segunda categoría calculada por ley, listado con filtros por período y anulación dentro del plazo legal

El recurso /bhe emite Boletas de Honorarios Electrónicas por el pipeline REST del SII (loa.sii.cl/cgi_BHE/). No interviene certificado digital: la autenticación contra el SII usa la clave tributaria custodiada cifrada de tu org, así que no se manda X-Cert-Id.

Base URL: https://app.notta.cl/api/v1. Autenticación: Authorization: Bearer ntt_cert_… — ver Autenticación. La emisión exige Idempotency-Key.

La retención de segunda categoría la calcula Notta según la tabla de la Ley 21.420 — no se puede sobrescribir desde el input:

Año de emisiónTasa
Antes de 202310%
202312,25%
202413%
202514,5%
2026 y 202717%

Si el receptor es persona natural sin giro (persona_natural_sin_giro: true), la retención es 0 y el líquido es igual al bruto.

Endpoints

POST /bhe

Emite una BHE: calcula retención y líquido según el año, persiste el documento y encola el envío REST al SII.

CampoTipoRequeridoDescripción
rut_emisorstringsíRUT del emisor persona, p. ej. 12345678-5.
receptor.rutstringsíRUT del receptor, p. ej. 76123456-0.
receptor.razon_socialstringsí1–100 caracteres (se recorta whitespace).
receptor.persona_natural_sin_girobooleansítrue → retención 0 (consumidor final).
fecha_emisionstringsíYYYY-MM-DD.
monto_brutointsíCLP enteros, positivo.
descripcionstringsí1–1000 caracteres.
sii_envenumnocert (default) o prod.
curl -X POST https://app.notta.cl/api/v1/bhe \
  -H "Authorization: Bearer ntt_cert_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "rut_emisor": "12345678-5",
    "receptor": { "rut": "76123456-0", "razon_social": "Cliente Ejemplo SpA", "persona_natural_sin_giro": false },
    "fecha_emision": "2026-06-09",
    "monto_bruto": 1000000,
    "descripcion": "Asesoría tributaria junio 2026"
  }'

Respuesta 202 Accepted (bruto 1.000.000 en 2026 → retención 17% = 170.000, líquido 830.000):

{
  "id": "01977f5d-4e80-7000-8000-000000000004",
  "status": "queued",
  "sii_status": "queued",
  "tasa_retencion": 0.17,
  "monto_retencion": 170000,
  "monto_liquido": 830000,
  "period_year": 2026,
  "period_month": 6,
  "links": { "self": "/api/v1/bhe/01977f5d-4e80-7000-8000-000000000004" }
}

Errores posibles:

CódigoHTTPnext_action
idempotency_key_missing400—
invalid_json400—
validation_failed (incluye issues[] de Zod)400—
unauthorized · invalid_api_key · api_key_revoked · api_key_expired401—
billing.free_tier_exceeded402upgrade_plan
bhe.credential.invalid (clave tributaria no configurada o rechazada)401configure_bhe_credential
bhe.receptor.tipo_invalid422fix_receptor_and_retry
bhe.retencion.mismatch422use_calculated_retencion

GET /bhe

Lista las BHE de tu organización, con filtros por período tributario y estado.

Query paramTipoRequeridoDescripción
period_yearintnoAño del período tributario.
period_monthintnoMes del período (1–12).
anuladabooleannotrue / false.
sii_statusstringnoFiltra por estado SII.
limitintno1–100, default 50.
sortenumnofolio · period · monto_bruto · monto_liquido · sii_status · created_at.
direnumnoasc · desc.
curl "https://app.notta.cl/api/v1/bhe?period_year=2026&period_month=6&anulada=false" \
  -H "Authorization: Bearer ntt_cert_..."

Respuesta 200 OK:

{
  "bhes": [
    {
      "id": "01977f5d-4e80-7000-8000-000000000004",
      "folio": 12,
      "period_year": 2026,
      "period_month": 6,
      "rut_emisor": "12345678-5",
      "rut_receptor": "76123456-0",
      "razon_social_receptor": "Cliente Ejemplo SpA",
      "receptor_persona_natural_sin_giro": false,
      "descripcion": "Asesoría tributaria junio 2026",
      "monto_bruto": 1000000,
      "tasa_retencion": "0.1700",
      "monto_retencion": 170000,
      "monto_liquido": 830000,
      "sii_status": "EPR",
      "sii_env": "cert",
      "anulada": false,
      "anulada_at": null,
      "anulada_reason": null,
      "track_id": null,
      "fecha_emision": "2026-06-09",
      "created_at": "2026-06-09T17:10:33.000Z",
      "links": { "self": "/api/v1/bhe/01977f5d-4e80-7000-8000-000000000004" }
    }
  ],
  "next_cursor": null
}

El array viene bajo la clave bhes. Errores posibles: 401 de autenticación.

Ojo con el tipo de tasa_retencion: el POST /bhe la devuelve como número (0.17), pero los GET la devuelven como string ("0.1700"), tal cual se serializa la columna numérica.

GET /bhe/:id

Devuelve el detalle de una BHE con montos, estado SII y datos de anulación si aplica (mismo shape que cada elemento del listado).

curl https://app.notta.cl/api/v1/bhe/01977f5d-4e80-7000-8000-000000000004 \
  -H "Authorization: Bearer ntt_cert_..."

Errores posibles:

CódigoHTTPnext_action
bhe.not_found404—

POST /bhe/:id/anular

Anula una BHE dentro del plazo legal; la marca anulada localmente y la anulación SII corre en el workflow.

CampoTipoRequeridoDescripción
razonstringsíMotivo de anulación, 1–250 caracteres.

Plazo legal de anulación: 3 meses

La BHE solo se puede anular dentro de 3 meses calendario desde la emisión. Pasado el plazo la API responde 422 bhe.plazo_anulacion.expired y el camino que queda es la rectificación manual ante el SII.

curl -X POST https://app.notta.cl/api/v1/bhe/01977f5d-4e80-7000-8000-000000000004/anular \
  -H "Authorization: Bearer ntt_cert_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "razon": "Servicio no prestado" }'

Respuesta 200 OK:

{ "id": "01977f5d-4e80-7000-8000-000000000004", "anulada": true, "folio": 12 }

Errores posibles:

CódigoHTTPnext_action
invalid_json400—
validation_failed (incluye issues[] de Zod)400—
bhe.not_found404—
bhe.plazo_anulacion.expired422consult_sii_or_manual_rectification

Próximos pasos

Última actualización

Anterior

API: Boletas

Siguiente

API: Certificados

En esta página