# Solicitar anulación de honorarios (beta)

> Solicita una única anulación del documento y motivo aprobados con referencia vigente y protocolo certificado.



{/* AUTO-GENERATED by @emisso/codegen. DO NOT EDIT. */}

|                     |                                                                   |
| ------------------- | ----------------------------------------------------------------- |
| **Tool ID**         | `sii.honorario.anular`                                            |
| **Nombre MCP**      | `sii__honorario__anular`                                          |
| **Conector**        | `sii`                                                             |
| **Plano**           | `action`                                                          |
| **Scope (permiso)** | `sii:honorarios:annul`                                            |
| **Auth**            | `connection_credentials`                                          |
| **Versión**         | `1`                                                               |
| **Sensible**        | sí                                                                |
| **Deprecado**       | no                                                                |
| **Comportamiento**  | readOnly=false, destructive=true, idempotent=true, openWorld=true |

> **Requiere conexión.** Indica cuál en cada llamada: header `X-Connect-Connection` en REST, campo `connectionId` en el `execute_write` de MCP y en las opciones del SDK. No hay resolución implícita, ni siquiera con una sola conexión activa: la conexión es la empresa. El id sale de [`conexiones.estado.consultar`](../conexiones/estado-consultar).

## Qué hace [#qué-hace]

Exige Idempotency-Key UUID v4. Un resultado desconocido se consulta y concilia con la misma operación; ninguna clave nueva autoriza repetir el POST. El estado fiscal y la atribución del resultado se informan por separado.

## Entrada [#entrada]

| Campo        | Tipo                                | Requerido | Descripción                                                                     |
| ------------ | ----------------------------------- | --------- | ------------------------------------------------------------------------------- |
| `previewRef` | string `^bhcp1\.[A-Za-z0-9_-]{43}$` | sí        | Referencia opaca del preview vigente y aprobado de esta solicitud de anulación. |

<details>
  <summary>
    JSON Schema de entrada
  </summary>

  ```json
  {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "previewRef": {
        "type": "string",
        "pattern": "^bhcp1\\.[A-Za-z0-9_-]{43}$",
        "description": "Referencia opaca del preview vigente y aprobado de esta solicitud de anulación."
      }
    },
    "required": [
      "previewRef"
    ],
    "additionalProperties": false
  }
  ```
</details>

## Salida [#salida]

| Campo                       | Tipo                                                                                                                          | Requerido | Descripción                                                                                                             |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------- |
| `resultado`                 | objeto                                                                                                                        | sí        | Resultado durable de la anulación, con estado fiscal y atribución separados.                                            |
| `resultado.estado`          | `"anulada"` · `"pendiente_receptor"` · `"rechazada"` · `"revision_administrativa"` · `"resultado_desconocido"`                | sí        | Resultado de la solicitud; resultado\_desconocido exige consultar y reconciliar el mismo intento, sin repetir el envío. |
| `resultado.solicitudId`     | string `^bhc_[A-Za-z0-9_-]+$`                                                                                                 | sí        | ID de la solicitud de anulación cuyo resultado durable se informa.                                                      |
| `resultado.puedeReintentar` | booleano                                                                                                                      | sí        | Siempre false: el envío fiscal final de esta solicitud nunca se repite.                                                 |
| `resultado.atribucion`      | `"own_response"` · `"observed_external"` · `"unknown"`                                                                        | sí        | Origen de la evidencia: respuesta propia correlacionada, observación externa o atribución desconocida.                  |
| `resultado.estadoFiscal`    | `"vigente"` · `"vigente_anulacion_pendiente"` · `"anulada"` · `"observada_receptor"` · `"observada_unidad"` · `"desconocido"` | sí        | Estado fiscal observado de la boleta; una observación no demuestra por sí sola que esta solicitud causó el cambio.      |

<details>
  <summary>
    JSON Schema de salida
  </summary>

  ```json
  {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "resultado": {
        "type": "object",
        "properties": {
          "estado": {
            "type": "string",
            "enum": [
              "anulada",
              "pendiente_receptor",
              "rechazada",
              "revision_administrativa",
              "resultado_desconocido"
            ],
            "description": "Resultado de la solicitud; resultado_desconocido exige consultar y reconciliar el mismo intento, sin repetir el envío."
          },
          "solicitudId": {
            "type": "string",
            "maxLength": 128,
            "pattern": "^bhc_[A-Za-z0-9_-]+$",
            "description": "ID de la solicitud de anulación cuyo resultado durable se informa."
          },
          "puedeReintentar": {
            "type": "boolean",
            "const": false,
            "description": "Siempre false: el envío fiscal final de esta solicitud nunca se repite."
          },
          "atribucion": {
            "type": "string",
            "enum": [
              "own_response",
              "observed_external",
              "unknown"
            ],
            "description": "Origen de la evidencia: respuesta propia correlacionada, observación externa o atribución desconocida."
          },
          "estadoFiscal": {
            "type": "string",
            "enum": [
              "vigente",
              "vigente_anulacion_pendiente",
              "anulada",
              "observada_receptor",
              "observada_unidad",
              "desconocido"
            ],
            "description": "Estado fiscal observado de la boleta; una observación no demuestra por sí sola que esta solicitud causó el cambio."
          }
        },
        "required": [
          "estado",
          "solicitudId",
          "puedeReintentar",
          "atribucion",
          "estadoFiscal"
        ],
        "additionalProperties": false,
        "description": "Resultado durable de la anulación, con estado fiscal y atribución separados."
      }
    },
    "required": [
      "resultado"
    ],
    "additionalProperties": false
  }
  ```
</details>

## Errores de esta tool [#errores-de-esta-tool]

| Código                           | HTTP | Reintentable | Qué hacer                                                                                                                                                                                |
| -------------------------------- | ---- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `connection_disabled`            | 403  | no           | Reactívala en /connections o usa otra conexión del mismo sistema.                                                                                                                        |
| `connection_credential_required` | 428  | no           | Crea un enlace con conexiones.enlace.crear (modo reconectar si la conexión ya existe) y pide a la persona que entregue la credencial de nuevo. No reintentes con la credencial anterior. |
| `connection_busy`                | 409  | sí           | Espera unos segundos y reintenta. Es una espera transitoria: no necesitas volver a conectar ni ingresar la credencial otra vez.                                                          |
| `upstream_error`                 | 502  | sí           | Reintenta más tarde. Si persiste, el problema está en el sistema externo, no en tu integración.                                                                                          |
| `timeout`                        | 504  | sí           | Reintenta. Para sincronizaciones largas usa la vía asíncrona y consulta el estado del trabajo.                                                                                           |

Toda llamada puede devolver además los códigos transversales (`validation_error`, `unauthorized`, `scope_not_granted`, `rate_limited`, entre otros): el detalle vive en el [catálogo de errores](../errores).