Pedir boletas de honorarios a tus profesionales

Una clínica que paga honorarios necesita una boleta de cada profesional. Con Connect, tu sistema crea la solicitud con los datos de la boleta y le envía un enlace a la profesional. Al abrirlo, ve qué se le pide, entrega su clave del SII en el widget de Connect, revisa el borrador y autoriza esa boleta exacta. Tú recibes el folio y el PDF original del SII, nunca su clave.

La demo sigue a una clínica que paga las consultas de la primera quincena a una pediatra.

▍

Antes de empezar

• Una clave de API con el permiso sii:honorarios:write, creada en API keys.
• Un endpoint de webhooks para enterarte de la emisión sin consultar a cada rato. Es opcional: también puedes leer el estado de la solicitud.
• Los datos de la boleta: quién la emite, a quién, por qué servicios, en qué fecha y el monto bruto.
• La profesional necesita su propia clave tributaria del SII. No necesita una cuenta en Emisso, y la clínica no necesita una conexión del SII para pedir la boleta.

Los pasos

1. Tu sistema crea la solicitud

Al cerrar la liquidación de honorarios, tu sistema llama a la API con los datos de la boleta. La cabecera Idempotency-Key es obligatoria: si repites la llamada con la misma clave, recibes la misma solicitud y no se crea otra.

curl -X POST https://connect.emisso.ai/api/v1/honorarios_requests \
  -H "Authorization: Bearer connect_sk_..." \
  -H "Idempotency-Key: 2f6c1d8e-5b0a-4c7e-9a31-0d4e8b7f2c55" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "puntual",
    "payload": {
      "rut_emisor": "15842663-3",
      "rut_receptor": "76104222-K",
      "nombre_receptor": "Clínica Valle Austral SpA",
      "domicilio_receptor": "Av. Los Leones 1180, piso 3",
      "region_receptor": "13",
      "comuna_receptor": "Providencia",
      "fecha": "2026-09-29",
      "glosa": "Consultas de pediatría, 1 al 15 de septiembre 2026",
      "monto_bruto_clp": 1260000,
      "retiene": "receptor",
      "referencia": "HON-2026-09-PM"
    }
  }'

{
  "data": {
    "created": true,
    "request": {
      "id": "bhr_v7mq2klx9tcr4hn8wzd3p",
      "mode": "puntual",
      "status": "awaiting_authorization",
      "phase": "prepared",
      "session_id": "cs_n4pw8rzt3hyb6kq2mfj7s",
      "connection_id": null,
      "authorization_id": null,
      "document_version": 1,
      "emission_status": "pending",
      "document_status": "pending",
      "delivery_status": "pending",
      "access_status": "pending",
      "folio": null,
      "document_id": null,
      "error_code": null,
      "expires_at": "2026-09-30T14:05:12.000Z",
      "created_at": "2026-09-29T14:05:12.000Z",
      "updated_at": "2026-09-29T14:05:12.000Z"
    },
    "hosted_url": "https://connect.emisso.ai/c/connect_cs_..."
  },
  "meta": { "request_id": "req_k2df7smv5qxl9tb3nwr8c" }
}

La respuesta (201) trae la solicitud en estado awaiting_authorization y su enlace en hosted_url. El enlace vence en 24 horas; puedes acortarlo con expires_in_seconds. folio llega en null hasta que la boleta se emite. Si repites la llamada con la misma Idempotency-Key, recibes 200 con created: false y la misma solicitud.

En el cuerpo de la llamada:

• rut_emisor es la profesional; rut_receptor y los demás datos _receptor son la clínica.
• monto_bruto_clp es el bruto en pesos enteros, nunca el líquido.
• retiene: "receptor" indica que la clínica hace la retención; con "emisor" la hace la profesional.
• referencia es tu identificador de negocio, único por organización y emisor. No se recicla.

2. Le envías el enlace a cada profesional

Por correo, WhatsApp o dentro de tu propia app: el canal lo eliges tú. El enlace sirve solo para esta boleta, y abrirlo o administrar la clínica no autoriza nada: solo la profesional, con su clave.

3. Abre el enlace y ve el widget

Ve qué clínica le pide la boleta, por qué servicios y por cuánto. Nada se emite sin su autorización. Si no reconoce la solicitud, la devuelve y la boleta no se emite.

4. Entrega su acceso al SII

Escribe su RUT y su clave tributaria en el widget de Connect. Connect entra al SII y prepara el borrador. Tu sistema nunca ve la clave.

5. Revisa el borrador y autoriza la boleta

Ve la boleta tal como la armó el SII, con la retención y el total a recibir, y autoriza esa boleta exacta.

6. Connect la emite y tú recibes la boleta

La boleta queda registrada en el SII. Tu sistema recibe el webhook sii.honorarios.issued y, cuando el PDF está guardado, sii.honorarios.document_available. Los webhooks no traen RUT, montos ni el PDF: consulta la solicitud con GET /api/v1/honorarios_requests/{id} para ver el folio y descarga el PDF original con GET /api/v1/honorarios_requests/{id}/document, que entrega una URL firmada por 300 segundos.

Lo que garantiza

• Tu sistema nunca ve la clave. La profesional la entrega directamente en el widget de Connect.
• La profesional autoriza la boleta exacta. Ve el borrador que armó el SII antes de que se emita.
• Una solicitud, una boleta. Cerrar la ventana o pulsar dos veces no emite de nuevo. Si un resultado no se puede confirmar, Connect no lo reenvía.

Si algo falla

• La profesional devolvió la solicitud: queda en estado returned y no se emite nada. Si corriges los datos, crea una solicitud nueva.
• El enlace venció sin que la profesional autorizara: crea una solicitud nueva.
• Quieres retirarla antes de que se emita: POST /api/v1/honorarios_requests/{id}/cancel. Si el envío al SII ya empezó, no la cancela: devuelve su estado.
• Llega sii.honorarios.inconclusive: Connect no pudo confirmar todavía si el SII registró la boleta y sigue consultando esa misma operación. No la emitas por otro medio hasta que se aclare.
• Llega sii.honorarios.rejected: la emisión fue rechazada y la boleta no se emitió. Revisa el estado de la solicitud.

El contrato completo está en la referencia de la API: crear una solicitud.