Emitir la anulación de una factura o boleta en el SII


Tool ID	`sii.anulacion.emitir`
Nombre MCP	`sii__anulacion__emitir`
Conector	`sii`
Plano	`action`
Scope (permiso)	`sii:write`
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 y campo connectionId en el execute_write de MCP. 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.

Qué hace

EN EL SII FIRMAR ES EMITIR: el portal envía el documento en el mismo acto, así que no hay ensayo previo ni vuelta atrás, y el documento queda anulado. Exige previewRef vigente e Idempotency-Key explícita. La confirmación de la preparación ocurre dentro de esta llamada cuando la hace el mismo actor que la creó, sea una clave de API o una persona. La clave del certificado se resuelve en el servidor desde la conexión y nunca viaja en la llamada ni en el resultado. Un resultado desconocido se reconcilia contra la lista de documentos del portal; nunca autoriza reenviar. Un segundo emitir sobre el mismo previewRef NO duplica: la preparación va de pendiente a confirmada a consumida, así que el reintento falla en vez de emitir otra nota. Lo que decide la Idempotency-Key es si ese reintento recibe la respuesta guardada o un error sobre el mismo desenlace real.

Entrada

Campo	Tipo	Requerido	Descripción
`previewRef`	string	sí	Referencia devuelta por sii.anulacion.previsualizar; debe estar vigente y pertenecer a la misma conexión. Si la preparó el mismo actor, esta llamada la confirma.

JSON Schema de entrada

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "previewRef": {
      "type": "string",
      "minLength": 1,
      "description": "Referencia devuelta por sii.anulacion.previsualizar; debe estar vigente y pertenecer a la misma conexión. Si la preparó el mismo actor, esta llamada la confirma."
    }
  },
  "required": [
    "previewRef"
  ],
  "additionalProperties": false
}

Ejemplo

curl

curl -X POST https://connect.emisso.ai/api/v1/tools/sii.anulacion.emitir/execute \
  -H "Authorization: Bearer connect_sk_…" \
  -H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \
  -H "Idempotency-Key: 9d1f4c2a-7b30-4e58-9c11-2f6a8de5b743" \
  -H "Content-Type: application/json" \
  -d '{"input":{"previewRef":"anr.1.1789482000000.Qm9Lr3Tx7Vb1Nz5Kc8Wp2Hs4.Jd6Yf0Ga9Ue3Ko7Mt1Rw5Xq8.Lb2Zn6Cv4Ej0Ph8Si3Dk7Fu1"}}'

MCP · meta-tool execute_write

{
  "tool": "sii.anulacion.emitir",
  "params": {
    "previewRef": "anr.1.1789482000000.Qm9Lr3Tx7Vb1Nz5Kc8Wp2Hs4.Jd6Yf0Ga9Ue3Ko7Mt1Rw5Xq8.Lb2Zn6Cv4Ej0Ph8Si3Dk7Fu1"
  },
  "connectionId": "conn_9tKfR2mQx4Vb",
  "idempotencyKey": "9d1f4c2a-7b30-4e58-9c11-2f6a8de5b743"
}

Clave de idempotencia obligatoria. Sin ella la llamada responde idempotency_key_missing. Genera un UUID v4 nuevo por operación y envíalo en Idempotency-Key (REST) o en idempotencyKey (MCP). Repite la misma clave solo al reintentar esa operación.

Salida esperada (200):

{
  "data": {
    "resultado": {
      "estado": "emitida",
      "tipoDte": "61",
      "puedeReintentar": false,
      "operacionId": "req_p3n8x2c6v1b9m4k7w0q5z",
      "folio": "87",
      "fechaEmision": "2026-09-15",
      "confirmadoEn": "2026-09-15T14:08:41.000Z",
      "xmlFirmado": "<DTE xmlns=\"http://www.sii.cl/SiiDte\" version=\"1.0\"><Documento ID=\"…\"><Encabezado><IdDoc><TipoDTE>61</TipoDTE><Folio>87</Folio><FchEmis>2026-09-15</FchEmis></IdDoc><Emisor><RUTEmisor>76987654-5</RUTEmisor>…</Emisor><Receptor><RUTRecep>77123456-9</RUTRecep>…</Receptor><Totales><MntNeto>548000</MntNeto><TasaIVA>19.00</TasaIVA><IVA>104120</IVA><MntTotal>652120</MntTotal></Totales></Encabezado>…<Referencia><NroLinRef>1</NroLinRef><TpoDocRef>33</TpoDocRef><FolioRef>1042</FolioRef><FchRef>2026-09-15</FchRef><CodRef>1</CodRef>…</Referencia>…<TED version=\"1.0\">…</TED>…</Documento><Signature xmlns=\"http://www.w3.org/2000/09/xmldsig#\">…</Signature></DTE>"
    }
  },
  "meta": {
    "request_id": "req_…",
    "tool_id": "sii.anulacion.emitir",
    "plane": "action",
    "latency_ms": 7410,
    "audit_status": "recorded"
  }
}

Primero previsualiza con sii.anulacion.previsualizar: emitir solo acepta lo previsualizado y se reintenta con la misma Idempotency-Key. El folio es el de la nota de crédito, no el del documento anulado. Paso a paso en Anular o corregir un documento.

Salida

Campo	Tipo	Requerido	Descripción
`resultado`	valor	sí	Desenlace tributario allowlisted de la operación.

JSON Schema de salida

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "resultado": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "tipoDte": {
              "type": "string",
              "const": "61",
              "description": "Nota de crédito electrónica."
            },
            "puedeReintentar": {
              "type": "boolean",
              "const": false,
              "description": "Siempre false: firmar en el SII envía en el mismo acto, así que nada autoriza repetirlo."
            },
            "estado": {
              "type": "string",
              "const": "emitida",
              "description": "El portal lista la nota y su firma es la misma que Connect envió: el documento quedó anulado."
            },
            "operacionId": {
              "type": "string",
              "pattern": "^req_[0-9a-z]{21}$",
              "description": "Identificador estable de la operación regulada."
            },
            "folio": {
              "type": "string",
              "pattern": "^[1-9][0-9]*$",
              "description": "Folio de la nota de crédito, en texto y sólo con identidad concluyente."
            },
            "fechaEmision": {
              "type": "string",
              "x-emisso-formato": "AAAA-MM-DD",
              "description": "Fecha de emisión de la nota de crédito, confirmada en el portal."
            },
            "confirmadoEn": {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
              "description": "Instante en que Connect obtuvo la confirmación concluyente de la anulación."
            },
            "xmlFirmado": {
              "type": "string",
              "minLength": 1,
              "maxLength": 1048576,
              "description": "XML del DTE firmado que Connect envió y el SII aceptó, con su timbre electrónico (TED). Basta para generar la representación impresa y el PDF417. Es el documento tributario: guárdalo como tal."
            }
          },
          "required": [
            "tipoDte",
            "puedeReintentar",
            "estado",
            "operacionId",
            "folio",
            "fechaEmision",
            "confirmadoEn"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "tipoDte": {
              "type": "string",
              "const": "61",
              "description": "Nota de crédito electrónica."
            },
            "puedeReintentar": {
              "type": "boolean",
              "const": false,
              "description": "Siempre false: firmar en el SII envía en el mismo acto, así que nada autoriza repetirlo."
            },
            "estado": {
              "type": "string",
              "const": "rechazada",
              "description": "La nota no llegó a enviarse: el documento sigue vigente y se puede preparar la anulación de nuevo."
            },
            "operacionId": {
              "type": "string",
              "pattern": "^req_[0-9a-z]{21}$",
              "description": "Identificador estable de la operación regulada."
            },
            "motivo": {
              "type": "string",
              "enum": [
                "rechazo_concluyente_sin_emision"
              ],
              "description": "Motivo seguro del rechazo confirmado."
            }
          },
          "required": [
            "tipoDte",
            "puedeReintentar",
            "estado",
            "operacionId",
            "motivo"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "tipoDte": {
              "type": "string",
              "const": "61",
              "description": "Nota de crédito electrónica."
            },
            "puedeReintentar": {
              "type": "boolean",
              "const": false,
              "description": "Siempre false: firmar en el SII envía en el mismo acto, así que nada autoriza repetirlo."
            },
            "estado": {
              "type": "string",
              "const": "resultado_desconocido",
              "description": "Evidencia insuficiente para afirmar emisión o rechazo."
            },
            "operacionId": {
              "type": "string",
              "pattern": "^req_[0-9a-z]{21}$",
              "description": "Identificador estable de la operación regulada."
            },
            "siguientePaso": {
              "type": "string",
              "const": "reconciliacion_automatica_o_soporte",
              "description": "Consultar la evidencia por reconciliación o soporte; nunca reenviar."
            }
          },
          "required": [
            "tipoDte",
            "puedeReintentar",
            "estado",
            "operacionId",
            "siguientePaso"
          ],
          "additionalProperties": false
        }
      ],
      "description": "Desenlace tributario allowlisted de la operación."
    }
  },
  "required": [
    "resultado"
  ],
  "additionalProperties": false
}

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_not_found`	404	no	Usa uno de los connectionId que lista el error, o revisa la conexión en /connections. No hace falta reactivar nada.
`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.