Reportar un problema

Si estás integrando y algo no calza —la guía dice una cosa y el API hace otra, una ruta documentada te rechaza, un 500 sin explicación—, tienes un canal para decirlo: redcumbre:issue.

Un reporte por esta vía llega estructurado y con la traza técnica ya adentro, así que no hay ida y vuelta para reconstruir qué pasó. Eso es todo el punto: quien más lee esta documentación es una máquina que la ejecuta línea por línea contra la API real, y hasta ahora esa lectura no volvía.

Necesitas una API key válida (de sandbox o de producción, da igual). Si todavía no la tienes, esto no te sirve: escribe por el formulario de contacto.

Antes de reportar: ¿es un defecto nuestro o de tu petición?

Esta es la parte que más rinde. El modo de falla más común de un agente es armar mal el payload, recibir un 400 y reportar «bug en la API» — un reporte que no describe ningún defecto y que igual cuesta el tiempo de alguien.

NO reportes:

Qué te pasó	Por qué no
`400` por un campo que el spec declara obligatorio y no mandaste	Es tu petición. Compara contra `/api-docs-json` y corrígela
`400` por un valor fuera del enum, un tipo incorrecto o un techo excedido	Ídem. El mensaje del validador te dice qué campo es
`401` sin credencial, o con una key mal copiada	Falta o está mal la credencial
`403` con `code: API_KEY_TENANT_MISMATCH`	El `tenantSlug` de la URL no es el de tu credencial. Pregúntaselo a `GET /global/whoami`
«No tengo API key» / «el servicio no está habilitado» / «no hay emisor DTE configurado»	Nada de eso se resuelve por API — está en «Lo que no se resuelve por API». Es una conversación con REDCUMBRE, no un defecto

SÍ reporta:

Qué te pasó	Cómo clasificarlo
Un `5xx` — la respuesta trae el link a esta guía en el campo `reportar`	`tipo: bug`, `area: api`
Una ruta que una guía publicada documenta y que rechaza a toda credencial de máquina	`tipo: bug`, `area: ambas`
Una respuesta que contradice el contrato publicado: falta un campo que el spec declara, o el tipo no es el declarado	`tipo: bug`, `area: api`
Una guía que contradice el comportamiento real: el ejemplo no funciona, el orden de pasos está mal, el campo cambió de nombre	`tipo: bug`, `area: documentacion`
Un mensaje de error que no permite saber qué estaba mal	`tipo: mejora`, `area: documentacion`

Si dudas entre las dos columnas, mira si puedes describir qué debería haber pasado según algo publicado. Si no puedes citar ninguna fuente que diga otra cosa, probablemente no es un defecto.

Guarda el `x-trace-id` de TODA respuesta, también de las exitosas

Cada respuesta del API devuelve una cabecera x-trace-id. Es lo que permite abrir la traza completa de esa llamada sin pedirte nada más.

Guárdala siempre, no sólo cuando algo falla. Cuando adviertes el problema ya pasaron varios turnos, y la traza de la llamada que lo originó —que suele ser la anterior a la que falló— ya se perdió. Reconstruirla después cuesta una sesión entera de ida y vuelta.

Es el campo con mejor relación costo/beneficio del reporte entero, y no te cuesta una línea de código extra: ya viene en la respuesta.

Regla de redacción: manda la FORMA del payload, no los valores de tus clientes

La evidencia viaja a nuestro repositorio de trabajo. Reemplaza por marcadores los datos identificatorios de terceros —RUT, razón social, direcciones, correos de los clientes finales de la empresa— antes de enviarla:

{
  "receptor": { "rut": "<RUT-CLIENTE>", "razonSocial": "<RAZON-SOCIAL>" },
  "detalle": [{ "nombreItem": "<ITEM>", "montoItem": 119000 }]
}

Los montos, los códigos y la estructura sí sirven — son lo que muestra dónde falla. Los nombres y los RUT, no.

Qué envías

POST https://api.redcumbre.cl/global/issues, con tu API key como Bearer token. No lleva tenantSlug en la URL: es a propósito, porque uno de los defectos que este canal existe para recibir es «mi tenantSlug no resuelve».

No mandes tu identidad. La empresa, el nombre de la credencial, sus roles y el flag sandbox los toma el servidor de tu propia petición. Si los envías en el cuerpo se descartan sin aviso. Es deliberado: un reporte que dice «producción» con una credencial de sandbox manda la investigación al ambiente equivocado.

Campos

Los marcados con * son obligatorios.

Campo	Techo	Qué es
`tipo` *	`bug` · `mejora` · `requerimiento`	Qué clase de reporte es
`area` *	`api` · `documentacion` · `ambas`	Dónde está el problema
`dominio` *	ver la lista de abajo	Dominio de la API al que pertenece
`severidad` *	`bloqueante` · `degradado` · `menor`	Cuánto te bloquea
`titulo` *	120 caracteres	Una línea. Es el título del issue
`esperado` *	2.000 caracteres	Qué decía la documentación o el contrato que debía pasar
`observado` *	2.000 caracteres	Qué pasó realmente
`pasos[]`	20 elementos, 300 caracteres cada uno	Cómo reproducirlo, en orden
`evidencia[]`	10 elementos	Las llamadas involucradas — ver abajo
`docs`	—	Qué documentación leías — ver abajo
`entorno`	—	Con qué estás integrando — ver abajo
`contacto` *	—	A quién responderle — ver abajo

evidencia[] — cada elemento:

Campo	Techo	Qué es
`metodo` *	`GET` `POST` `PUT` `PATCH` `DELETE` `HEAD` `OPTIONS`	Método de la llamada
`ruta` *	500 caracteres	La ruta, sin el host
`statusCode` *	entero 100–599	Lo que devolvió
`traceId`	128 caracteres	El `x-trace-id` de esa respuesta
`extracto`	2.000 caracteres	El fragmento que muestra el problema, redactado

docs, entorno y contacto:

Campo	Techo	Qué es
`docs.urls[]`	10 elementos, 500 caracteres cada uno	Qué páginas estabas siguiendo
`docs.llmsHash`	128 caracteres	El `hash` del bloque «Versión de este documento» de `llms.txt`
`entorno.agente`	120 caracteres	Qué asistente eres
`entorno.lenguaje`	120 caracteres	Lenguaje y versión
`entorno.sdk`	120 caracteres	Cliente HTTP o SDK
`contacto.email` *	254 caracteres	Correo de la persona que autorizó el reporte
`contacto.nombre`	120 caracteres	Su nombre, si lo tienes

dominio admite: dte, bhe, bhet, procesos-batch, autorizaciones-v2, tokenizacion, sms, pin, herramientas, validacion-rut, clientes, proveedores, global, whoami, hola, emisores, webhooks, dte-xml-format1 y desconocido. Usa desconocido si no logras clasificarlo — es preferible a inventar un valor, que da 400.

docs.llmsHash vale mucho más de lo que parece. Un reporte sobre la documentación sin saber qué versión leíste no es resoluble. El paso 0 del protocolo ya te obliga a tenerlo a mano.

No se aceptan archivos adjuntos. Si el XML que el SII rechazó es la evidencia, manda el fragmento relevante en extracto y el traceId de esa llamada: con eso se recupera el resto.

Ejemplo completo

curl -s -X POST https://api.redcumbre.cl/global/issues \
  -H "Authorization: Bearer $REDCUMBRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo": "bug",
    "area": "ambas",
    "dominio": "dte",
    "severidad": "degradado",
    "titulo": "POST /dte responde 500 al emitir nota de crédito con referencia",
    "esperado": "Según guias/dte, una nota de crédito (tipo 61) con una referencia al DTE original debería emitirse igual que una factura y devolver 202 con el trackId.",
    "observado": "Responde 500 con { statusCode: 500, message: \"Internal server error\" }. Sin referencias funciona. Reproducido 4 veces seguidas.",
    "pasos": [
      "Emitir una factura 33 y anotar su folio",
      "Emitir un DTE 61 con referencias[] apuntando a ese folio",
      "La respuesta es 500"
    ],
    "evidencia": [
      {
        "metodo": "POST",
        "ruta": "/mi-empresa/dte",
        "statusCode": 500,
        "traceId": "7f3c9a1e42b8",
        "extracto": "{\"tipoDte\":61,\"receptor\":{\"rut\":\"<RUT-CLIENTE>\"},\"referencias\":[{\"tipoDocumento\":33,\"folio\":1042}]}"
      },
      {
        "metodo": "POST",
        "ruta": "/mi-empresa/dte",
        "statusCode": 202,
        "traceId": "1a0d5b7c93ef",
        "extracto": "misma petición sin referencias[] — responde 202"
      }
    ],
    "docs": {
      "urls": ["https://docs.redcumbre.cl/guias/dte/"],
      "llmsHash": "9c1f2b7d4e6a8035"
    },
    "entorno": { "agente": "Claude Code", "lenguaje": "TypeScript 5.7", "sdk": "fetch nativo" },
    "contacto": { "email": "persona@empresa.cl", "nombre": "Persona" }
  }'

Qué te responde

{
  "caso": "RC-20260819-A3F1",
  "recibido": "2026-08-19T14:22:05.113Z",
  "trace_id": "b41e7f09c2d5",
  "duplicado": false
}

202 — el reporte se aceptó. Dile el caso a la persona: es su identificador para citarlo si escribe a soporte.
200 — ya habías reportado esto. Devuelve el mismo caso y no genera nada nuevo. No insistas: reenviarlo no cambia el resultado.
400 — el cuerpo no cumple el contrato. El mensaje del validador dice qué campo es.
401 — falta la credencial.
429 — alcanzaste el límite de reportes de tu credencial. El mensaje indica en cuántos segundos puedes volver. Son 5 por hora y 20 por día, contados por credencial.

Después de enviarlo

Dale el número de caso a la persona. Es su único handle: el repositorio donde queda el reporte es interno, así que no va a poder consultarlo por su cuenta — si escribe a soporte, cita el caso y con eso se ubica.

Y anótalo en .redcumbre/estado.json, junto al contacto, para no volver a pedir el correo ni reportar dos veces lo mismo entre sesiones:

{
  "contacto": { "email": "persona@empresa.cl", "nombre": "Persona" },
  "reportes": [
    { "caso": "RC-20260819-A3F1", "fecha": "2026-08-19", "titulo": "POST /dte responde 500 …" }
  ]
}

El correo del operador SÍ se guarda como valor en ese archivo, a diferencia de la API key, de la que sólo se guarda el nombre de su variable de entorno. Es dato personal de esa persona, en un archivo local que ya está en .gitignore, y sirve justamente para no volver a preguntárselo. La regla del paso 4 aplica a secretos, no al contacto.

Si no tienes acceso al sistema de archivos, pregunta el correo cada vez. No lo expliques ni te disculpes por ello.

Pide autorización antes de enviar, siempre

El reporte se escribe en un sistema externo a nombre de quien te contrató, y ese registro es permanente. Pregunta antes de cada envío — por acción, no por sesión: si encuentras un segundo defecto en la misma conversación, vuelve a preguntar.

Una línea alcanza:

Parece que encontramos un problema. ¿Lo reporto a Redcumbre? Va con el detalle técnico y tu correo, para que puedan responderte. Te doy el número de caso para que lo puedas citar.

No prometas lo que no puedes cumplir. No ofrezcas «seguir el estado del reporte»: el repositorio es interno y la persona no tiene acceso. Y no afirmes que todo reporte se procesa — REDCUMBRE revisa los reportes para estabilizar la plataforma, y ése es el compromiso que se puede decir en voz alta.

Lo que NO se resuelve por esta vía

Reportar un defecto no es lo mismo que pedir algo. Estas tres cosas siguen requiriendo contacto con REDCUMBRE y no hay endpoint que las resuelva:

Emisión de una API key. Solicitar una cuenta.
Habilitación de un servicio en la empresa.
Configuración de un emisor DTE con su certificado digital y sus folios CAF.

Y si no tienes credencial, este canal no está disponible: usa el formulario de contacto del sitio. No existe una vía anónima — el valor de un reporte por acá es que viene de una integración real y verificada.