{
 "openapi": "3.1.0",
 "info": {
  "title": "API de Trevol",
  "version": "2026-10-22",
  "description": "Facturación electrónica de Colombia (DIAN). Con una llave se emiten las facturas de venta (incluida la exportación, la moneda extranjera, el AIU, los mandatos, el transporte, los notarios, las divisas y el sector salud) y sus notas crédito y débito; el documento soporte y su nota de ajuste; el documento equivalente electrónico (tiquete POS y los otros nueve tipos) y su nota de ajuste; la nómina electrónica (102) y su nota de ajuste (103); y los eventos RADIAN 030 a 034. Cada llave es de una empresa y un ambiente: tvl_test_ (habilitación real de la DIAN) o tvl_live_ (producción). Mensajes en español, campos en inglés. Versiones: la `2026-10-22` (la de las llaves nuevas) responde 202 `processing` cuando la DIAN no contesta y Trevol termina el documento (no crees otro para la misma operación); la `2026-10-21` (las llaves anteriores) responde 503 `dian_unavailable`. El encabezado `Trevol-Version` manda sobre la versión de la llave. La fase 3 es aditiva: no hay versión nueva. En habilitación, el set de pruebas de la nómina, del documento equivalente y de los eventos responde 202 `validating` en las dos versiones. El PDF, el ZIP y el correo se hacen después del 201 en los documentos que los llevan: espera el evento `….delivered` o consulta `delivery.status`. Avisos firmados con Standard Webhooks (sección `webhooks`; el catálogo tiene 49 tipos y un endpoint creado antes de la fase 3 con `*` sigue recibiendo solo los 22 de antes hasta que se guarde de nuevo su lista de eventos). El saldo prepago de la cuenta (lo comparten sus empresas) se consulta en `/v1/balance` y se recarga con Wompi (`POST /v1/balance/top_ups`). Documentación: https://platform.trevol.si/docs"
 },
 "servers": [
  {
   "url": "https://api.trevol.si/v1"
  }
 ],
 "security": [
  {
   "llave": []
  }
 ],
 "tags": [
  {
   "name": "General",
   "description": "Salud, la empresa de la llave y la consulta de adquirientes."
  },
  {
   "name": "Saldo",
   "description": "El saldo prepago de la cuenta (lo comparten sus empresas), sus movimientos y las recargas con Wompi."
  },
  {
   "name": "Facturas",
   "description": "Emitir, consultar, corregir y reenviar facturas electrónicas, incluidas la exportación, la moneda extranjera, el AIU, los mandatos, el transporte, los notarios, las divisas y el sector salud."
  },
  {
   "name": "Notas crédito",
   "description": "Notas crédito electrónicas."
  },
  {
   "name": "Notas débito",
   "description": "Notas débito electrónicas."
  },
  {
   "name": "Documento soporte",
   "description": "Documento soporte en adquisiciones a no obligados a facturar (05) y su nota de ajuste (95). Se generan, no se expiden: sin PDF, ZIP ni correo."
  },
  {
   "name": "Documento equivalente",
   "description": "Documento equivalente electrónico (tiquete POS 20 y los tipos 25, 27, 30, 35, 40, 45, 50, 55 y 60) y su nota de ajuste (crédito 94 y débito 93). Se expiden como la factura: PDF, ZIP y correo."
  },
  {
   "name": "Nómina electrónica",
   "description": "Documento soporte de pago de nómina electrónica (102) y su nota de ajuste (103: Reemplazar o Eliminar). Un 102 por trabajador y por mes en producción (y en habilitación cuando la empresa ya pasó el set de pruebas). Sin PDF ni correo: `xml`, `zip` y `dian_response`. El trabajador solo sale al dueño de la llave."
  },
  {
   "name": "Eventos RADIAN",
   "description": "Eventos sobre facturas: el acuse (030), el reclamo (031), el recibo del bien (032) y la aceptación expresa (033) de una factura RECIBIDA, y la aceptación tácita (034) de una factura PROPIA a crédito. Un rechazo es final: el siguiente intento es otro evento. Solo `xml`. Los eventos 035 a 051 necesitan un participante RADIAN y no están disponibles."
  },
  {
   "name": "Webhooks",
   "description": "Endpoints que reciben avisos firmados (Standard Webhooks) cuando un documento cambia."
  },
  {
   "name": "Eventos",
   "description": "Los eventos que Trevol manda a tus webhooks, guardados 30 días, y su reenvío."
  },
  {
   "name": "Registro de peticiones",
   "description": "Qué pidió tu software a la API, cómo le fue y cuánto tardó (30 días, sin cuerpos)."
  }
 ],
 "paths": {
  "/health": {
   "get": {
    "summary": "Salud",
    "security": [],
    "responses": {
     "200": {
      "description": "ok",
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "General"
    ],
    "operationId": "getHealth"
   }
  },
  "/company": {
   "get": {
    "summary": "La empresa de la llave",
    "description": "La empresa de la llave: NIT, razón social, ambiente y numeraciones activas. Desde la fase 3 trae `capabilities`, un resumen de lo que ESTA llave puede emitir ahora: documento soporte (con su numeración), documento equivalente (con los prefijos POS), nómina (`status`: `enabled`, `testing`, `not_registered` o `not_enabled`, según el ambiente de la llave) y eventos RADIAN (representante legal). Es informativo: si una lectura falla, esa clave no aparece.",
    "responses": {
     "200": {
      "description": "La empresa, su ambiente y sus numeraciones activas",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Company"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "General"
    ],
    "operationId": "retrieveCompany"
   }
  },
  "/dian/acquirer": {
   "get": {
    "summary": "Datos del adquiriente en la DIAN",
    "parameters": [
     {
      "name": "document_type",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "document_number",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "{found, name, email}",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Acquirer"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "General"
    ],
    "operationId": "retrieveDianAcquirer"
   }
  },
  "/requests": {
   "get": {
    "summary": "El registro de peticiones de la empresa y el ambiente de la llave (30 días)",
    "description": "Cada petición que pasó la autenticación de una llave, aunque terminara en 403, 422 o 429. Sin cuerpos, consultas, IP ni llaves; `path` es la plantilla.",
    "parameters": [
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 100
      }
     },
     {
      "name": "starting_after",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "status",
      "in": "query",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "key_id",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "created_from",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "created_to",
      "in": "query",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "{object: list, data: [RequestLog], has_more, next_cursor}",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "object",
          "data",
          "has_more",
          "next_cursor"
         ],
         "properties": {
          "object": {
           "type": "string",
           "enum": [
            "list"
           ]
          },
          "data": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/RequestLog"
           }
          },
          "has_more": {
           "type": "boolean"
          },
          "next_cursor": {
           "type": [
            "string",
            "null"
           ]
          }
         }
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Registro de peticiones"
    ],
    "operationId": "listRequests"
   }
  },
  "/webhook_endpoints": {
   "get": {
    "summary": "Los endpoints de webhooks de la empresa y el ambiente",
    "description": "Los de la empresa y el ambiente de la llave (máximo 5). Las llaves de lectura ven el esquema y el host de la `url`, con el camino enmascarado («https://tu-servidor.co/…»): a veces es un secreto. Las de escritura la ven completa.",
    "responses": {
     "200": {
      "description": "{object: list, data, has_more, next_cursor}",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "object",
          "data",
          "has_more",
          "next_cursor"
         ],
         "properties": {
          "object": {
           "type": "string",
           "enum": [
            "list"
           ]
          },
          "data": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/WebhookEndpoint"
           }
          },
          "has_more": {
           "type": "boolean"
          },
          "next_cursor": {
           "type": [
            "string",
            "null"
           ]
          }
         }
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Webhooks"
    ],
    "operationId": "listWebhookEndpoints"
   },
   "post": {
    "summary": "Crear un endpoint de webhooks (máximo 5 por empresa y ambiente)",
    "description": "El `secret` (whsec_…) viene SOLO en esta respuesta. Cada entrega lleva `webhook-id` (el mismo en cada reintento: deduplica con él), `webhook-timestamp` y `webhook-signature`: `v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)), con la clave de los 32 bytes que siguen a `whsec_`. No usa Idempotency-Key: la respuesta lleva el secreto y no se guarda.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/WebhookEndpointInput"
       },
       "examples": {
        "ejemplo": {
         "summary": "Tres eventos de facturación",
         "value": {
          "url": "https://tu-servidor.co/webhooks/trevol",
          "description": "Producción: facturación",
          "events": [
           "invoice.accepted",
           "invoice.rejected",
           "credit_note.accepted"
          ]
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "El endpoint, con su `secret`",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/WebhookEndpoint"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "409": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "422": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Webhooks"
    ],
    "operationId": "createWebhookEndpoint"
   }
  },
  "/webhook_endpoints/{id}": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Un endpoint",
    "description": "El endpoint (nunca el secreto: solo se muestra al crear o rotar). Un id de otra empresa o de otro ambiente es 404.",
    "responses": {
     "200": {
      "description": "El recurso",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/WebhookEndpoint"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Webhooks"
    ],
    "operationId": "retrieveWebhookEndpoint"
   },
   "patch": {
    "summary": "Cambiar la URL, la descripción, los eventos o pausar y reactivar",
    "description": "Solo cambia lo que mandes. `status: paused` cancela las entregas pendientes; `status: enabled` reactiva el endpoint (también uno que Trevol desactivó por fallos sostenidos) y pone en cero el contador de fallos. `disabled` no se puede pedir.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/WebhookEndpointUpdate"
       },
       "examples": {
        "ejemplo": {
         "summary": "Pausar el endpoint",
         "value": {
          "description": "Pausado mientras migramos el servidor",
          "status": "paused"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "El recurso",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/WebhookEndpoint"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "422": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Webhooks"
    ],
    "operationId": "updateWebhookEndpoint"
   },
   "delete": {
    "summary": "Borrar el endpoint (con sus entregas)",
    "description": "Tu servidor deja de recibir avisos de inmediato. No se puede deshacer; si solo quieres detenerlo un rato, pausa el endpoint.",
    "responses": {
     "200": {
      "description": "{id, object: webhook_endpoint, deleted: true}",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/DeletedObject"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Webhooks"
    ],
    "operationId": "deleteWebhookEndpoint"
   }
  },
  "/webhook_endpoints/{id}/rotate_secret": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "post": {
    "summary": "Rotar el secreto",
    "description": "El `secret` (whsec_…) viene SOLO en esta respuesta. Cada entrega lleva `webhook-id` (el mismo en cada reintento: deduplica con él), `webhook-timestamp` y `webhook-signature`: `v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)), con la clave de los 32 bytes que siguen a `whsec_`. El secreto anterior sigue firmando `grace_period_hours` (0 a 72; 24 por defecto): durante la gracia cada entrega lleva las dos firmas, separadas por un espacio.",
    "requestBody": {
     "required": false,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
         "grace_period_hours": {
          "type": "integer",
          "minimum": 0,
          "maximum": 72
         }
        }
       },
       "examples": {
        "gracia": {
         "summary": "El secreto anterior firma 24 horas más",
         "value": {
          "grace_period_hours": 24
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "El endpoint, con el `secret` nuevo",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/WebhookEndpoint"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "422": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Webhooks"
    ],
    "operationId": "rotateWebhookEndpointSecret"
   }
  },
  "/webhook_endpoints/{id}/test": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "post": {
    "summary": "Mandar un evento `webhook.test` solo a este endpoint (debe estar activo)",
    "description": "Encola una entrega manual de prueba (3 intentos) y despierta el envío: en segundos llega a tu servidor con la firma de siempre. Hasta 60 por hora. Mira cómo salió en …/deliveries.",
    "responses": {
     "202": {
      "description": "La entrega encolada",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/WebhookDelivery"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "409": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "429": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Webhooks"
    ],
    "operationId": "testWebhookEndpoint"
   }
  },
  "/webhook_endpoints/{id}/deliveries": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Las entregas de este endpoint, de la más nueva a la más vieja",
    "description": "Cada intento con su estado HTTP, su error (`timeout`, `http_5xx`, `blocked_address`…) y su duración. Nunca guardamos la respuesta de tu servidor. Se conservan 30 días.",
    "parameters": [
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 100
      }
     },
     {
      "name": "starting_after",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "status",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "pending",
        "sending",
        "succeeded",
        "failed",
        "canceled"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "{object: list, data, has_more, next_cursor}",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "object",
          "data",
          "has_more",
          "next_cursor"
         ],
         "properties": {
          "object": {
           "type": "string",
           "enum": [
            "list"
           ]
          },
          "data": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/WebhookDelivery"
           }
          },
          "has_more": {
           "type": "boolean"
          },
          "next_cursor": {
           "type": [
            "string",
            "null"
           ]
          }
         }
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Webhooks"
    ],
    "operationId": "listWebhookEndpointDeliveries"
   }
  },
  "/events": {
   "get": {
    "summary": "Los eventos de 30 días de la empresa y el ambiente",
    "description": "Solo se guardan eventos si la empresa tiene al menos un endpoint en este ambiente. Útil para recuperar lo que se perdió mientras tu servidor estaba caído.",
    "parameters": [
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 100
      }
     },
     {
      "name": "starting_after",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "type",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "created_from",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "created_to",
      "in": "query",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "{object: list, data, has_more, next_cursor}",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "object",
          "data",
          "has_more",
          "next_cursor"
         ],
         "properties": {
          "object": {
           "type": "string",
           "enum": [
            "list"
           ]
          },
          "data": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Event"
           }
          },
          "has_more": {
           "type": "boolean"
          },
          "next_cursor": {
           "type": [
            "string",
            "null"
           ]
          }
         }
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Eventos"
    ],
    "operationId": "listEvents"
   }
  },
  "/events/{id}": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Un evento",
    "description": "El evento tal como se mandó al endpoint.",
    "responses": {
     "200": {
      "description": "El recurso",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Event"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Eventos"
    ],
    "operationId": "retrieveEvent"
   }
  },
  "/events/{id}/resend": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "post": {
    "summary": "Reenviar un evento a un endpoint (entrega manual nueva; el `webhook-id` es el mismo)",
    "description": "Vuelve a mandar el evento a un endpoint activo de la misma empresa y el mismo ambiente. Lleva el mismo `webhook-id`: si tu servidor ya lo procesó, deduplica con él. Hasta 60 por hora.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
         "endpoint_id"
        ],
        "properties": {
         "endpoint_id": {
          "type": "string",
          "pattern": "^we_[0-9a-f]{32}$"
         }
        }
       },
       "examples": {
        "reenviar": {
         "summary": "Reenviar al endpoint indicado",
         "value": {
          "endpoint_id": "we_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
         }
        }
       }
      }
     }
    },
    "responses": {
     "202": {
      "description": "La entrega encolada",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/WebhookDelivery"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "409": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "429": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Eventos"
    ],
    "operationId": "resendEvent"
   }
  },
  "/balance": {
   "get": {
    "summary": "El saldo de la cuenta (lo comparten sus empresas)",
    "description": "El saldo prepago de Trevol. Es de la **cuenta**, no de la empresa: todas las empresas de la cuenta lo comparten (`shared: true`) y cualquier llave de cualquiera de ellas, de lectura o de escritura, `test` o `live`, ve el mismo. Solo lo que se emite en producción (llaves `live`) lo consume; la habilitación (`test`) no cobra. `available` es lo que se puede gastar (en pesos); `held`, lo apartado por documentos que la DIAN todavía valida; `overdraft`, cuánto puede bajar `available` de cero al apartar un documento; `low_threshold`, el umbral del aviso de saldo bajo (el 20 % de la última recarga; `null` sin recargas). `level`: `empty` con `available` ≤ 0, `low` por debajo de `low_threshold`, si no `ok`. Con `available` por debajo del precio de un documento, emitir en producción responde 402 `insufficient_balance`. El evento `balance.low` avisa por webhook.",
    "responses": {
     "200": {
      "description": "El saldo",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Balance"
        },
        "example": {
         "object": "balance",
         "currency": "COP",
         "available": 48600,
         "held": 400,
         "overdraft": 0,
         "low_threshold": 10000,
         "level": "ok",
         "updated_at": "2026-10-31T09:20:05-05:00",
         "shared": true
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Saldo"
    ],
    "operationId": "retrieveBalance"
   }
  },
  "/balance/transactions": {
   "get": {
    "summary": "Los movimientos del saldo de la cuenta",
    "description": "Los movimientos del saldo de la cuenta (de todas sus empresas), del más nuevo al más viejo: lo mismo que «Saldo y recargas» en la app. Un documento es UNA fila (`type: document`) con su `status`: `pending` (apartado mientras la DIAN lo valida), `charged` (validado y cobrado) o `released` (la DIAN lo rechazó: no se cobró y `amount` es 0); `company` dice qué empresa lo emitió. Lo demás es una fila por movimiento: `top_up` (recarga, con su `reference`), `top_up_reversal`, `bonus`, `adjustment`, `license_fee`, `expiration` u `other`. `amount` es lo que el movimiento hizo con el disponible, con signo; `available_after`, el disponible justo después. Filtro `type`: `all` (por defecto), `documents`, `funding` (todo lo que no es un documento) o `top_ups`. Paginación por cursor: `limit` (1 a 100, 25 por defecto) y `starting_after` (el `id` de la última fila que tienes).",
    "parameters": [
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 100,
       "default": 25
      }
     },
     {
      "name": "starting_after",
      "in": "query",
      "schema": {
       "type": "string",
       "pattern": "^btx_[0-9]{1,18}$"
      }
     },
     {
      "name": "type",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "all",
        "documents",
        "funding",
        "top_ups"
       ],
       "default": "all"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "{object: list, data, has_more, next_cursor}",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "object",
          "data",
          "has_more",
          "next_cursor"
         ],
         "properties": {
          "object": {
           "type": "string",
           "enum": [
            "list"
           ]
          },
          "data": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/BalanceTransaction"
           }
          },
          "has_more": {
           "type": "boolean"
          },
          "next_cursor": {
           "type": [
            "string",
            "null"
           ]
          }
         }
        },
        "example": {
         "object": "list",
         "has_more": true,
         "next_cursor": "btx_9300",
         "data": [
          {
           "id": "btx_9341",
           "object": "balance_transaction",
           "type": "document",
           "status": "pending",
           "amount": -400,
           "available_after": 48600,
           "description": "Factura FE1290 · apartado mientras la DIAN lo valida",
           "document": {
            "type": "invoice",
            "number": "FE1290"
           },
           "company": {
            "nit": "900373115",
            "name": "TOSTADORA MONTEVERDE SAS"
           },
           "reference": null,
           "created_at": "2026-10-31T09:20:05-05:00"
          },
          {
           "id": "btx_9338",
           "object": "balance_transaction",
           "type": "document",
           "status": "charged",
           "amount": -400,
           "available_after": 49000,
           "description": "Nómina NE15",
           "document": {
            "type": "payroll",
            "number": "NE15"
           },
           "company": {
            "nit": "900373591",
            "name": "CAFÉ DEL VALLE SAS"
           },
           "reference": null,
           "created_at": "2026-10-31T08:02:41-05:00"
          },
          {
           "id": "btx_9301",
           "object": "balance_transaction",
           "type": "document",
           "status": "released",
           "amount": 0,
           "available_after": 49000,
           "description": "Factura FE1289 · rechazado por la DIAN: no se cobró",
           "document": {
            "type": "invoice",
            "number": "FE1289"
           },
           "company": {
            "nit": "900373115",
            "name": "TOSTADORA MONTEVERDE SAS"
           },
           "reference": null,
           "created_at": "2026-10-30T17:10:00-05:00"
          },
          {
           "id": "btx_9300",
           "object": "balance_transaction",
           "type": "top_up",
           "status": "completed",
           "amount": 50000,
           "available_after": 49400,
           "description": "Recarga TRV-REC-20261030-8F2A61C0D9B3",
           "document": null,
           "company": null,
           "reference": "TRV-REC-20261030-8F2A61C0D9B3",
           "created_at": "2026-10-30T16:58:12-05:00"
          }
         ]
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "422": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Saldo"
    ],
    "operationId": "listBalanceTransactions"
   }
  },
  "/balance/top_ups": {
   "post": {
    "summary": "Preparar una recarga del saldo (para el widget de Wompi)",
    "description": "Prepara una recarga del saldo de la cuenta y devuelve lo que necesita el widget de Wompi (`WidgetCheckout`: `publicKey`, `currency`, `amountInCents`, `reference`, `signature: {integrity}` y `expirationTime`). El pago se hace en el widget; cuando Wompi lo aprueba, Trevol abona el saldo (y la factura de la recarga sale a nombre de `buyer`). Preparar no mueve saldo y la firma vence en una hora: si el widget venció, prepara otra. Solo llaves de escritura; exige `Idempotency-Key` (repetir con la misma clave devuelve la MISMA recarga). Sin `buyer`, la factura va a nombre de la empresa de la llave con sus datos (NIT, DV, razón social, correo, teléfono, dirección y municipio); si no alcanzan, 422 en `buyer.*`. El monto va entre la recarga mínima y la máxima (422 `top_up_below_minimum` / `top_up_above_maximum` con `minimum_cop` / `maximum_cop`). Es dinero real con cualquier llave (también `test`): el saldo es uno solo. Hasta 20 por llave cada 10 minutos (429).",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "required": true,
      "description": "Obligatoria: 1 a 255 caracteres ASCII visibles, única por pedido (7 días).",
      "schema": {
       "type": "string",
       "maxLength": 255
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/TopUpInput"
       },
       "examples": {
        "empresa": {
         "summary": "A nombre de la empresa de la llave",
         "value": {
          "amount_cop": 50000
         }
        },
        "comprador": {
         "summary": "Con otro comprador para la factura",
         "value": {
          "amount_cop": 50000,
          "buyer": {
           "document_type": "31",
           "document_number": "900373115",
           "check_digit": "3",
           "person_type": "legal",
           "name": "TOSTADORA MONTEVERDE SAS",
           "email": "contabilidad@monteverde.example",
           "phone": "3001234567",
           "address": "Cra 5 # 10-20",
           "municipality_code": "76001"
          }
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "La recarga preparada",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/TopUp"
        },
        "example": {
         "object": "top_up",
         "reference": "TRV-REC-20261031-4C1D2E3F4A5B",
         "amount_cop": 50000,
         "status": "prepared",
         "wompi": {
          "public_key": "pub_prod_Ejemplo0000000000000000000000",
          "reference": "TRV-REC-20261031-4C1D2E3F4A5B",
          "amount_in_cents": 5000000,
          "currency": "COP",
          "signature": "5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d",
          "expiration_time": "2026-10-31T15:20:05.000Z"
         }
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "422": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        },
        "examples": {
         "minima": {
          "summary": "Menos que la recarga mínima",
          "value": {
           "type": "https://platform.trevol.si/docs/errores#top_up_below_minimum",
           "title": "La recarga es menor que la mínima",
           "status": 422,
           "code": "top_up_below_minimum",
           "detail": "El monto es menor que la recarga mínima ($5.000).",
           "retryable": false,
           "minimum_cop": 5000,
           "request_id": "req_5b1c5b1c5b1c5b1c5b1c5b1c"
          }
         },
         "comprador": {
          "summary": "Los datos de la empresa no alcanzan para la factura",
          "value": {
           "type": "https://platform.trevol.si/docs/errores#validation_error",
           "title": "Los datos no son válidos",
           "status": 422,
           "code": "validation_error",
           "detail": "Los datos de la empresa no alcanzan para la factura de la recarga: complétalos en la app (ficha de la empresa) o manda `buyer`.",
           "retryable": false,
           "errors": [
            {
             "field": "buyer.email",
             "pointer": "/buyer/email",
             "message": "En los datos de la empresa: el correo para enviar la factura no es válido."
            }
           ],
           "request_id": "req_5b1c5b1c5b1c5b1c5b1c5b1c"
          }
         }
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "429": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "503": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        },
        "examples": {
         "no_disponible": {
          "summary": "Las recargas no están disponibles",
          "value": {
           "type": "https://platform.trevol.si/docs/errores#top_ups_unavailable",
           "title": "Las recargas no están disponibles",
           "status": 503,
           "code": "top_ups_unavailable",
           "detail": "Las recargas no están disponibles en este momento. Vuelve a intentarlo más tarde.",
           "retryable": true,
           "retry_after": 300,
           "request_id": "req_5b1c5b1c5b1c5b1c5b1c5b1c"
          }
         }
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     }
    },
    "tags": [
     "Saldo"
    ],
    "operationId": "createBalanceTopUp"
   }
  },
  "/invoices": {
   "post": {
    "summary": "Emitir una factura",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "required": true,
      "description": "Obligatoria: 1 a 255 caracteres ASCII visibles, única por pedido (7 días).",
      "schema": {
       "type": "string",
       "maxLength": 255
      }
     },
     {
      "name": "Trevol-Version",
      "in": "header",
      "required": false,
      "description": "La versión de la API. Si no viene, la de la llave (las llaves de antes quedan en 2026-10-21; las nuevas nacen en 2026-10-22).",
      "schema": {
       "type": "string",
       "enum": [
        "2026-10-21",
        "2026-10-22"
       ]
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/InvoiceInput"
       },
       "examples": {
        "venta": {
         "summary": "Venta nacional en pesos, a crédito",
         "value": {
          "external_id": "VENTA-2026-000123",
          "customer": {
           "document_type": "31",
           "document_number": "900123456",
           "name": "COMERCIALIZADORA ANDINA SAS",
           "person_type": "legal",
           "email": "facturacion@comercializadoraandina.example",
           "address": "Calle 72 # 10-34, Oficina 501",
           "municipality_code": "11001"
          },
          "items": [
           {
            "code": "LIC-ANUAL",
            "description": "Licencia anual de software",
            "quantity": "2",
            "unit_price": "150000",
            "taxes": [
             {
              "code": "01",
              "rate": "19"
             }
            ]
           },
           {
            "code": "SOP-MES",
            "description": "Soporte técnico mensual",
            "quantity": "1",
            "unit_price": "80000",
            "taxes": [
             {
              "code": "01",
              "rate": "19"
             }
            ]
           }
          ],
          "payment": {
           "form": "credit",
           "term_days": 30
          },
          "notes": [
           "Gracias por su compra"
          ]
         }
        },
        "exportacion": {
         "summary": "Exportación en dólares",
         "value": {
          "external_id": "EXP-77",
          "document_type": "02",
          "currency": {
           "code": "USD",
           "exchange_rate": "3950.12",
           "rate_date": "2026-10-21"
          },
          "delivery_terms": {
           "incoterm": "FOB",
           "conditions": "Puerto de Cartagena"
          },
          "customer": {
           "document_type": "50",
           "document_number": "US123456789",
           "name": "ACME INC",
           "country": "US",
           "city": "Miami",
           "region": "Florida",
           "postal_code": "33131",
           "address": "200 S Biscayne Blvd"
          },
          "items": [
           {
            "description": "Consultoría",
            "quantity": "1",
            "unit_price": "1000",
            "taxes": [
             {
              "code": "01",
              "excluded": true
             }
            ]
           }
          ],
          "payment": {
           "form": "credit",
           "term_days": 30
          }
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Document"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "202": {
      "description": "Versión 2026-10-22: la DIAN no contestó (`status: processing`; Trevol termina el documento y avisa por webhook; no crees otro documento para la misma venta, y si repites con la misma Idempotency-Key respondemos sin enviar) o el documento se está enviando (`status: sending`); también la contingencia (`status: contingency`). Lleva `Location` y, salvo la contingencia, `Retry-After: 30`. En 2026-10-21 la DIAN sin contestar es un 503 `dian_unavailable`.",
      "headers": {
       "Location": {
        "schema": {
         "type": "string"
        }
       },
       "Retry-After": {
        "schema": {
         "type": "integer"
        }
       },
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Document"
        }
       }
      }
     },
     "402": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "409": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "422": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "429": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "503": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     }
    },
    "description": "Valida, numera, firma y envía una factura a la DIAN. Además de la factura nacional acepta la exportación (`document_type: \"02\"`), la moneda extranjera (`currency`), los términos de entrega (`delivery_terms`), el AIU, los mandatos, el transporte de carga, los notarios, las divisas y el sector salud (`operation_type`). El envío físico de la mercancía va en `shipment` (no en `delivery`: ese es el estado del PDF, el ZIP y el correo en la respuesta). Las notas crédito y débito no admiten estos campos.\n\n**Respuestas.** `201` la DIAN lo validó (`status: accepted`). `202` solo en la versión 2026-10-22: la DIAN no contestó (`processing`), otra petición lo está enviando (`sending`) o, en habilitación, el set de pruebas todavía lo valida (`validating`, en las dos versiones); trae `Location` y `Retry-After`, y el resultado llega por GET y por webhook: **no crees otro documento para la misma operación**. `422` `validation_error` (se revisó a fondo ANTES de reservar: no se gastó el número, y `errors[]` dice el campo), `dian_rejected` (con `document` y las reglas traducidas; corrige con `PUT` y el mismo número), `company_not_enabled` o `numbering_unavailable` (con `reason`). `402` `insufficient_balance` (producción sin saldo: queda `pending` con su número). `409` `external_id_in_use` o `duplicate_document` (con `existing_id`). `503` `dian_unavailable` en la 2026-10-21. Pide `Idempotency-Key`: repetir la misma devuelve lo mismo sin enviar nada.",
    "tags": [
     "Facturas"
    ],
    "operationId": "createInvoice"
   },
   "get": {
    "summary": "Listar (factura)",
    "parameters": [
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 100
      }
     },
     {
      "name": "starting_after",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "status",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "external_id",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "created_from",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "created_to",
      "in": "query",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "{object: list, data, has_more, next_cursor}",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "object",
          "data",
          "has_more",
          "next_cursor"
         ],
         "properties": {
          "object": {
           "type": "string",
           "enum": [
            "list"
           ]
          },
          "data": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Document"
           }
          },
          "has_more": {
           "type": "boolean"
          },
          "next_cursor": {
           "type": [
            "string",
            "null"
           ]
          }
         }
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Facturas"
    ],
    "operationId": "listInvoices"
   }
  },
  "/invoices/preview": {
   "post": {
    "summary": "Calcular una factura sin emitirla",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/InvoiceInput"
       },
       "examples": {
        "venta": {
         "summary": "Venta nacional en pesos, a crédito",
         "value": {
          "external_id": "VENTA-2026-000123",
          "customer": {
           "document_type": "31",
           "document_number": "900123456",
           "name": "COMERCIALIZADORA ANDINA SAS",
           "person_type": "legal",
           "email": "facturacion@comercializadoraandina.example",
           "address": "Calle 72 # 10-34, Oficina 501",
           "municipality_code": "11001"
          },
          "items": [
           {
            "code": "LIC-ANUAL",
            "description": "Licencia anual de software",
            "quantity": "2",
            "unit_price": "150000",
            "taxes": [
             {
              "code": "01",
              "rate": "19"
             }
            ]
           },
           {
            "code": "SOP-MES",
            "description": "Soporte técnico mensual",
            "quantity": "1",
            "unit_price": "80000",
            "taxes": [
             {
              "code": "01",
              "rate": "19"
             }
            ]
           }
          ],
          "payment": {
           "form": "credit",
           "term_days": 30
          },
          "notes": [
           "Gracias por su compra"
          ]
         }
        },
        "exportacion": {
         "summary": "Exportación en dólares",
         "value": {
          "external_id": "EXP-77",
          "document_type": "02",
          "currency": {
           "code": "USD",
           "exchange_rate": "3950.12",
           "rate_date": "2026-10-21"
          },
          "delivery_terms": {
           "incoterm": "FOB",
           "conditions": "Puerto de Cartagena"
          },
          "customer": {
           "document_type": "50",
           "document_number": "US123456789",
           "name": "ACME INC",
           "country": "US",
           "city": "Miami",
           "region": "Florida",
           "postal_code": "33131",
           "address": "200 S Biscayne Blvd"
          },
          "items": [
           {
            "description": "Consultoría",
            "quantity": "1",
            "unit_price": "1000",
            "taxes": [
             {
              "code": "01",
              "excluded": true
             }
            ]
           }
          ],
          "payment": {
           "form": "credit",
           "term_days": 30
          }
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Totales",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Preview"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Facturas"
    ],
    "operationId": "previewInvoice"
   }
  },
  "/invoices/{id}": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Una factura",
    "responses": {
     "200": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Document"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Facturas"
    ],
    "operationId": "retrieveInvoice"
   },
   "put": {
    "summary": "Corregir una factura rechazada (mismo número) y reenviarla",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "required": true,
      "description": "Obligatoria: 1 a 255 caracteres ASCII visibles, única por pedido (7 días).",
      "schema": {
       "type": "string",
       "maxLength": 255
      }
     },
     {
      "name": "Trevol-Version",
      "in": "header",
      "required": false,
      "description": "La versión de la API. Si no viene, la de la llave (las llaves de antes quedan en 2026-10-21; las nuevas nacen en 2026-10-22).",
      "schema": {
       "type": "string",
       "enum": [
        "2026-10-21",
        "2026-10-22"
       ]
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/InvoiceInput"
       },
       "examples": {
        "venta": {
         "summary": "Venta nacional en pesos, a crédito",
         "value": {
          "external_id": "VENTA-2026-000123",
          "customer": {
           "document_type": "31",
           "document_number": "900123456",
           "name": "COMERCIALIZADORA ANDINA SAS",
           "person_type": "legal",
           "email": "facturacion@comercializadoraandina.example",
           "address": "Calle 72 # 10-34, Oficina 501",
           "municipality_code": "11001"
          },
          "items": [
           {
            "code": "LIC-ANUAL",
            "description": "Licencia anual de software",
            "quantity": "2",
            "unit_price": "150000",
            "taxes": [
             {
              "code": "01",
              "rate": "19"
             }
            ]
           },
           {
            "code": "SOP-MES",
            "description": "Soporte técnico mensual",
            "quantity": "1",
            "unit_price": "80000",
            "taxes": [
             {
              "code": "01",
              "rate": "19"
             }
            ]
           }
          ],
          "payment": {
           "form": "credit",
           "term_days": 30
          },
          "notes": [
           "Gracias por su compra"
          ]
         }
        },
        "exportacion": {
         "summary": "Exportación en dólares",
         "value": {
          "external_id": "EXP-77",
          "document_type": "02",
          "currency": {
           "code": "USD",
           "exchange_rate": "3950.12",
           "rate_date": "2026-10-21"
          },
          "delivery_terms": {
           "incoterm": "FOB",
           "conditions": "Puerto de Cartagena"
          },
          "customer": {
           "document_type": "50",
           "document_number": "US123456789",
           "name": "ACME INC",
           "country": "US",
           "city": "Miami",
           "region": "Florida",
           "postal_code": "33131",
           "address": "200 S Biscayne Blvd"
          },
          "items": [
           {
            "description": "Consultoría",
            "quantity": "1",
            "unit_price": "1000",
            "taxes": [
             {
              "code": "01",
              "excluded": true
             }
            ]
           }
          ],
          "payment": {
           "form": "credit",
           "term_days": 30
          }
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Document"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "202": {
      "description": "Versión 2026-10-22: la DIAN no contestó (`status: processing`; Trevol termina el documento y avisa por webhook; no crees otro documento para la misma venta, y si repites con la misma Idempotency-Key respondemos sin enviar) o el documento se está enviando (`status: sending`); también la contingencia (`status: contingency`). Lleva `Location` y, salvo la contingencia, `Retry-After: 30`. En 2026-10-21 la DIAN sin contestar es un 503 `dian_unavailable`.",
      "headers": {
       "Location": {
        "schema": {
         "type": "string"
        }
       },
       "Retry-After": {
        "schema": {
         "type": "integer"
        }
       },
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Document"
        }
       }
      }
     },
     "409": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     }
    },
    "tags": [
     "Facturas"
    ],
    "operationId": "correctInvoice"
   }
  },
  "/invoices/{id}/send": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "post": {
    "summary": "Reenviar una pendiente o en error",
    "parameters": [
     {
      "name": "Trevol-Version",
      "in": "header",
      "required": false,
      "description": "La versión de la API. Si no viene, la de la llave (las llaves de antes quedan en 2026-10-21; las nuevas nacen en 2026-10-22).",
      "schema": {
       "type": "string",
       "enum": [
        "2026-10-21",
        "2026-10-22"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Document"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "202": {
      "description": "Versión 2026-10-22: la DIAN no contestó (`status: processing`; Trevol termina el documento y avisa por webhook; no crees otro documento para la misma venta, y si repites con la misma Idempotency-Key respondemos sin enviar) o el documento se está enviando (`status: sending`); también la contingencia (`status: contingency`). Lleva `Location` y, salvo la contingencia, `Retry-After: 30`. En 2026-10-21 la DIAN sin contestar es un 503 `dian_unavailable`.",
      "headers": {
       "Location": {
        "schema": {
         "type": "string"
        }
       },
       "Retry-After": {
        "schema": {
         "type": "integer"
        }
       },
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Document"
        }
       }
      }
     },
     "409": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Facturas"
    ],
    "operationId": "sendInvoice"
   }
  },
  "/invoices/{id}/pdf": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Archivo pdf",
    "responses": {
     "200": {
      "description": "pdf",
      "content": {
       "application/pdf": {
        "schema": {
         "type": "string",
         "format": "binary"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Facturas"
    ],
    "operationId": "downloadInvoicePdf"
   }
  },
  "/invoices/{id}/xml": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Archivo xml",
    "responses": {
     "200": {
      "description": "xml",
      "content": {
       "application/xml": {
        "schema": {
         "type": "string",
         "format": "binary"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Facturas"
    ],
    "operationId": "downloadInvoiceXml"
   }
  },
  "/invoices/{id}/zip": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Archivo zip",
    "responses": {
     "200": {
      "description": "zip",
      "content": {
       "application/zip": {
        "schema": {
         "type": "string",
         "format": "binary"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Facturas"
    ],
    "operationId": "downloadInvoiceZip"
   }
  },
  "/invoices/{id}/dian_response": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Archivo dian_response",
    "responses": {
     "200": {
      "description": "dian_response",
      "content": {
       "application/xml": {
        "schema": {
         "type": "string",
         "format": "binary"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Facturas"
    ],
    "operationId": "downloadInvoiceDianResponse"
   }
  },
  "/credit_notes": {
   "post": {
    "summary": "Emitir una nota crédito",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "required": true,
      "description": "Obligatoria: 1 a 255 caracteres ASCII visibles, única por pedido (7 días).",
      "schema": {
       "type": "string",
       "maxLength": 255
      }
     },
     {
      "name": "Trevol-Version",
      "in": "header",
      "required": false,
      "description": "La versión de la API. Si no viene, la de la llave (las llaves de antes quedan en 2026-10-21; las nuevas nacen en 2026-10-22).",
      "schema": {
       "type": "string",
       "enum": [
        "2026-10-21",
        "2026-10-22"
       ]
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/NoteInput"
       },
       "examples": {
        "devolucion": {
         "summary": "Devolución parcial de una factura de Trevol",
         "value": {
          "external_id": "DEV-2026-000045",
          "concept": "1",
          "description": "Devolución de una unidad por empaque dañado",
          "invoice": {
           "id": "inv_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
          },
          "items": [
           {
            "description": "Café especial 500 g",
            "code": "CAF-500",
            "unit": "94",
            "quantity": "1",
            "unit_price": "32000",
            "taxes": [
             {
              "code": "01",
              "rate": "19"
             }
            ]
           }
          ]
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Document"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "202": {
      "description": "Versión 2026-10-22: la DIAN no contestó (`status: processing`; Trevol termina el documento y avisa por webhook; no crees otro documento para la misma venta, y si repites con la misma Idempotency-Key respondemos sin enviar) o el documento se está enviando (`status: sending`); también la contingencia (`status: contingency`). Lleva `Location` y, salvo la contingencia, `Retry-After: 30`. En 2026-10-21 la DIAN sin contestar es un 503 `dian_unavailable`.",
      "headers": {
       "Location": {
        "schema": {
         "type": "string"
        }
       },
       "Retry-After": {
        "schema": {
         "type": "integer"
        }
       },
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Document"
        }
       }
      }
     },
     "402": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "409": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "422": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "429": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "503": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     }
    },
    "tags": [
     "Notas crédito"
    ],
    "operationId": "createCreditNote"
   },
   "get": {
    "summary": "Listar (nota crédito)",
    "parameters": [
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 100
      }
     },
     {
      "name": "starting_after",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "status",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "external_id",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "created_from",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "created_to",
      "in": "query",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "{object: list, data, has_more, next_cursor}",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "object",
          "data",
          "has_more",
          "next_cursor"
         ],
         "properties": {
          "object": {
           "type": "string",
           "enum": [
            "list"
           ]
          },
          "data": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Document"
           }
          },
          "has_more": {
           "type": "boolean"
          },
          "next_cursor": {
           "type": [
            "string",
            "null"
           ]
          }
         }
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Notas crédito"
    ],
    "operationId": "listCreditNotes"
   }
  },
  "/credit_notes/preview": {
   "post": {
    "summary": "Calcular una nota crédito sin emitirla",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/NoteInput"
       },
       "examples": {
        "devolucion": {
         "summary": "Devolución parcial de una factura de Trevol",
         "value": {
          "external_id": "DEV-2026-000045",
          "concept": "1",
          "description": "Devolución de una unidad por empaque dañado",
          "invoice": {
           "id": "inv_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
          },
          "items": [
           {
            "description": "Café especial 500 g",
            "code": "CAF-500",
            "unit": "94",
            "quantity": "1",
            "unit_price": "32000",
            "taxes": [
             {
              "code": "01",
              "rate": "19"
             }
            ]
           }
          ]
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Totales",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Preview"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Notas crédito"
    ],
    "operationId": "previewCreditNote"
   }
  },
  "/credit_notes/{id}": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Una nota crédito",
    "responses": {
     "200": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Document"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Notas crédito"
    ],
    "operationId": "retrieveCreditNote"
   },
   "put": {
    "summary": "Corregir una nota crédito rechazada (mismo número) y reenviarla",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "required": true,
      "description": "Obligatoria: 1 a 255 caracteres ASCII visibles, única por pedido (7 días).",
      "schema": {
       "type": "string",
       "maxLength": 255
      }
     },
     {
      "name": "Trevol-Version",
      "in": "header",
      "required": false,
      "description": "La versión de la API. Si no viene, la de la llave (las llaves de antes quedan en 2026-10-21; las nuevas nacen en 2026-10-22).",
      "schema": {
       "type": "string",
       "enum": [
        "2026-10-21",
        "2026-10-22"
       ]
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/NoteInput"
       },
       "examples": {
        "devolucion": {
         "summary": "Devolución parcial de una factura de Trevol",
         "value": {
          "external_id": "DEV-2026-000045",
          "concept": "1",
          "description": "Devolución de una unidad por empaque dañado",
          "invoice": {
           "id": "inv_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
          },
          "items": [
           {
            "description": "Café especial 500 g",
            "code": "CAF-500",
            "unit": "94",
            "quantity": "1",
            "unit_price": "32000",
            "taxes": [
             {
              "code": "01",
              "rate": "19"
             }
            ]
           }
          ]
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Document"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "202": {
      "description": "Versión 2026-10-22: la DIAN no contestó (`status: processing`; Trevol termina el documento y avisa por webhook; no crees otro documento para la misma venta, y si repites con la misma Idempotency-Key respondemos sin enviar) o el documento se está enviando (`status: sending`); también la contingencia (`status: contingency`). Lleva `Location` y, salvo la contingencia, `Retry-After: 30`. En 2026-10-21 la DIAN sin contestar es un 503 `dian_unavailable`.",
      "headers": {
       "Location": {
        "schema": {
         "type": "string"
        }
       },
       "Retry-After": {
        "schema": {
         "type": "integer"
        }
       },
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Document"
        }
       }
      }
     },
     "409": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     }
    },
    "tags": [
     "Notas crédito"
    ],
    "operationId": "correctCreditNote"
   }
  },
  "/credit_notes/{id}/send": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "post": {
    "summary": "Reenviar una pendiente o en error",
    "parameters": [
     {
      "name": "Trevol-Version",
      "in": "header",
      "required": false,
      "description": "La versión de la API. Si no viene, la de la llave (las llaves de antes quedan en 2026-10-21; las nuevas nacen en 2026-10-22).",
      "schema": {
       "type": "string",
       "enum": [
        "2026-10-21",
        "2026-10-22"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Document"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "202": {
      "description": "Versión 2026-10-22: la DIAN no contestó (`status: processing`; Trevol termina el documento y avisa por webhook; no crees otro documento para la misma venta, y si repites con la misma Idempotency-Key respondemos sin enviar) o el documento se está enviando (`status: sending`); también la contingencia (`status: contingency`). Lleva `Location` y, salvo la contingencia, `Retry-After: 30`. En 2026-10-21 la DIAN sin contestar es un 503 `dian_unavailable`.",
      "headers": {
       "Location": {
        "schema": {
         "type": "string"
        }
       },
       "Retry-After": {
        "schema": {
         "type": "integer"
        }
       },
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Document"
        }
       }
      }
     },
     "409": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Notas crédito"
    ],
    "operationId": "sendCreditNote"
   }
  },
  "/credit_notes/{id}/pdf": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Archivo pdf",
    "responses": {
     "200": {
      "description": "pdf",
      "content": {
       "application/pdf": {
        "schema": {
         "type": "string",
         "format": "binary"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Notas crédito"
    ],
    "operationId": "downloadCreditNotePdf"
   }
  },
  "/credit_notes/{id}/xml": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Archivo xml",
    "responses": {
     "200": {
      "description": "xml",
      "content": {
       "application/xml": {
        "schema": {
         "type": "string",
         "format": "binary"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Notas crédito"
    ],
    "operationId": "downloadCreditNoteXml"
   }
  },
  "/credit_notes/{id}/zip": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Archivo zip",
    "responses": {
     "200": {
      "description": "zip",
      "content": {
       "application/zip": {
        "schema": {
         "type": "string",
         "format": "binary"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Notas crédito"
    ],
    "operationId": "downloadCreditNoteZip"
   }
  },
  "/credit_notes/{id}/dian_response": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Archivo dian_response",
    "responses": {
     "200": {
      "description": "dian_response",
      "content": {
       "application/xml": {
        "schema": {
         "type": "string",
         "format": "binary"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Notas crédito"
    ],
    "operationId": "downloadCreditNoteDianResponse"
   }
  },
  "/debit_notes": {
   "post": {
    "summary": "Emitir una nota débito",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "required": true,
      "description": "Obligatoria: 1 a 255 caracteres ASCII visibles, única por pedido (7 días).",
      "schema": {
       "type": "string",
       "maxLength": 255
      }
     },
     {
      "name": "Trevol-Version",
      "in": "header",
      "required": false,
      "description": "La versión de la API. Si no viene, la de la llave (las llaves de antes quedan en 2026-10-21; las nuevas nacen en 2026-10-22).",
      "schema": {
       "type": "string",
       "enum": [
        "2026-10-21",
        "2026-10-22"
       ]
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/NoteInput"
       },
       "examples": {
        "intereses": {
         "summary": "Intereses de mora de una factura de Trevol",
         "value": {
          "external_id": "INT-2026-000012",
          "concept": "1",
          "description": "Intereses de mora de la factura de septiembre",
          "invoice": {
           "id": "inv_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
          },
          "items": [
           {
            "description": "Intereses de mora",
            "unit": "94",
            "quantity": "1",
            "unit_price": "45000"
           }
          ]
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Document"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "202": {
      "description": "Versión 2026-10-22: la DIAN no contestó (`status: processing`; Trevol termina el documento y avisa por webhook; no crees otro documento para la misma venta, y si repites con la misma Idempotency-Key respondemos sin enviar) o el documento se está enviando (`status: sending`); también la contingencia (`status: contingency`). Lleva `Location` y, salvo la contingencia, `Retry-After: 30`. En 2026-10-21 la DIAN sin contestar es un 503 `dian_unavailable`.",
      "headers": {
       "Location": {
        "schema": {
         "type": "string"
        }
       },
       "Retry-After": {
        "schema": {
         "type": "integer"
        }
       },
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Document"
        }
       }
      }
     },
     "402": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "409": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "422": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "429": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "503": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     }
    },
    "tags": [
     "Notas débito"
    ],
    "operationId": "createDebitNote"
   },
   "get": {
    "summary": "Listar (nota débito)",
    "parameters": [
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 100
      }
     },
     {
      "name": "starting_after",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "status",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "external_id",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "created_from",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "created_to",
      "in": "query",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "{object: list, data, has_more, next_cursor}",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "object",
          "data",
          "has_more",
          "next_cursor"
         ],
         "properties": {
          "object": {
           "type": "string",
           "enum": [
            "list"
           ]
          },
          "data": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Document"
           }
          },
          "has_more": {
           "type": "boolean"
          },
          "next_cursor": {
           "type": [
            "string",
            "null"
           ]
          }
         }
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Notas débito"
    ],
    "operationId": "listDebitNotes"
   }
  },
  "/debit_notes/preview": {
   "post": {
    "summary": "Calcular una nota débito sin emitirla",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/NoteInput"
       },
       "examples": {
        "intereses": {
         "summary": "Intereses de mora de una factura de Trevol",
         "value": {
          "external_id": "INT-2026-000012",
          "concept": "1",
          "description": "Intereses de mora de la factura de septiembre",
          "invoice": {
           "id": "inv_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
          },
          "items": [
           {
            "description": "Intereses de mora",
            "unit": "94",
            "quantity": "1",
            "unit_price": "45000"
           }
          ]
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Totales",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Preview"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Notas débito"
    ],
    "operationId": "previewDebitNote"
   }
  },
  "/debit_notes/{id}": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Una nota débito",
    "responses": {
     "200": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Document"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Notas débito"
    ],
    "operationId": "retrieveDebitNote"
   },
   "put": {
    "summary": "Corregir una nota débito rechazada (mismo número) y reenviarla",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "required": true,
      "description": "Obligatoria: 1 a 255 caracteres ASCII visibles, única por pedido (7 días).",
      "schema": {
       "type": "string",
       "maxLength": 255
      }
     },
     {
      "name": "Trevol-Version",
      "in": "header",
      "required": false,
      "description": "La versión de la API. Si no viene, la de la llave (las llaves de antes quedan en 2026-10-21; las nuevas nacen en 2026-10-22).",
      "schema": {
       "type": "string",
       "enum": [
        "2026-10-21",
        "2026-10-22"
       ]
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/NoteInput"
       },
       "examples": {
        "intereses": {
         "summary": "Intereses de mora de una factura de Trevol",
         "value": {
          "external_id": "INT-2026-000012",
          "concept": "1",
          "description": "Intereses de mora de la factura de septiembre",
          "invoice": {
           "id": "inv_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
          },
          "items": [
           {
            "description": "Intereses de mora",
            "unit": "94",
            "quantity": "1",
            "unit_price": "45000"
           }
          ]
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Document"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "202": {
      "description": "Versión 2026-10-22: la DIAN no contestó (`status: processing`; Trevol termina el documento y avisa por webhook; no crees otro documento para la misma venta, y si repites con la misma Idempotency-Key respondemos sin enviar) o el documento se está enviando (`status: sending`); también la contingencia (`status: contingency`). Lleva `Location` y, salvo la contingencia, `Retry-After: 30`. En 2026-10-21 la DIAN sin contestar es un 503 `dian_unavailable`.",
      "headers": {
       "Location": {
        "schema": {
         "type": "string"
        }
       },
       "Retry-After": {
        "schema": {
         "type": "integer"
        }
       },
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Document"
        }
       }
      }
     },
     "409": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     }
    },
    "tags": [
     "Notas débito"
    ],
    "operationId": "correctDebitNote"
   }
  },
  "/debit_notes/{id}/send": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "post": {
    "summary": "Reenviar una pendiente o en error",
    "parameters": [
     {
      "name": "Trevol-Version",
      "in": "header",
      "required": false,
      "description": "La versión de la API. Si no viene, la de la llave (las llaves de antes quedan en 2026-10-21; las nuevas nacen en 2026-10-22).",
      "schema": {
       "type": "string",
       "enum": [
        "2026-10-21",
        "2026-10-22"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Document"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "202": {
      "description": "Versión 2026-10-22: la DIAN no contestó (`status: processing`; Trevol termina el documento y avisa por webhook; no crees otro documento para la misma venta, y si repites con la misma Idempotency-Key respondemos sin enviar) o el documento se está enviando (`status: sending`); también la contingencia (`status: contingency`). Lleva `Location` y, salvo la contingencia, `Retry-After: 30`. En 2026-10-21 la DIAN sin contestar es un 503 `dian_unavailable`.",
      "headers": {
       "Location": {
        "schema": {
         "type": "string"
        }
       },
       "Retry-After": {
        "schema": {
         "type": "integer"
        }
       },
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Document"
        }
       }
      }
     },
     "409": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Notas débito"
    ],
    "operationId": "sendDebitNote"
   }
  },
  "/debit_notes/{id}/pdf": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Archivo pdf",
    "responses": {
     "200": {
      "description": "pdf",
      "content": {
       "application/pdf": {
        "schema": {
         "type": "string",
         "format": "binary"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Notas débito"
    ],
    "operationId": "downloadDebitNotePdf"
   }
  },
  "/debit_notes/{id}/xml": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Archivo xml",
    "responses": {
     "200": {
      "description": "xml",
      "content": {
       "application/xml": {
        "schema": {
         "type": "string",
         "format": "binary"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Notas débito"
    ],
    "operationId": "downloadDebitNoteXml"
   }
  },
  "/debit_notes/{id}/zip": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Archivo zip",
    "responses": {
     "200": {
      "description": "zip",
      "content": {
       "application/zip": {
        "schema": {
         "type": "string",
         "format": "binary"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Notas débito"
    ],
    "operationId": "downloadDebitNoteZip"
   }
  },
  "/debit_notes/{id}/dian_response": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Archivo dian_response",
    "responses": {
     "200": {
      "description": "dian_response",
      "content": {
       "application/xml": {
        "schema": {
         "type": "string",
         "format": "binary"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Notas débito"
    ],
    "operationId": "downloadDebitNoteDianResponse"
   }
  },
  "/support_documents": {
   "post": {
    "summary": "Emitir un documento soporte",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "required": true,
      "description": "Obligatoria: 1 a 255 caracteres ASCII visibles, única por pedido (7 días).",
      "schema": {
       "type": "string",
       "maxLength": 255
      }
     },
     {
      "name": "Trevol-Version",
      "in": "header",
      "required": false,
      "description": "La versión de la API. Si no viene, la de la llave (las llaves de antes quedan en 2026-10-21; las nuevas nacen en 2026-10-22).",
      "schema": {
       "type": "string",
       "enum": [
        "2026-10-21",
        "2026-10-22"
       ]
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/SupportDocumentInput"
       },
       "examples": {
        "compra": {
         "summary": "Compra de leche a un campesino",
         "value": {
          "external_id": "OC-991",
          "seller": {
           "resident": true,
           "person_type": "natural",
           "document_type": "31",
           "document_number": "1020304050",
           "name": "PEREZ GOMEZ ANA MARIA",
           "address": "Vereda El Silencio, finca La Esperanza",
           "municipality_code": "25053",
           "postal_code": "252007",
           "tax_responsibilities": [
            "R-99-PN"
           ]
          },
          "items": [
           {
            "description": "Leche cruda",
            "unit": "LTR",
            "quantity": "120",
            "unit_price": "1800"
           }
          ],
          "payment": {
           "form": "cash",
           "methods": [
            {
             "code": "10"
            }
           ]
          },
          "notes": [
           "Compra de la semana 42 de octubre"
          ]
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SupportDocument"
        },
        "example": {
         "id": "sd_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
         "object": "support_document",
         "environment": "test",
         "status": "accepted",
         "number": "DS994001",
         "prefix": "DS",
         "external_id": "OC-991",
         "origin": "api",
         "cuds": "abababababababababababababababababababababababababababababababababababababababababababababababab",
         "qr": "https://catalogo-vpfe-hab.dian.gov.co/document/searchqr?documentkey=abababababababababababababababababababababababababababababababababababababababababababababababab",
         "issued_at": "2026-10-23T09:15:02-05:00",
         "seller": {
          "resident": true,
          "person_type": "natural",
          "document_type": "31",
          "document_number": "1020304050",
          "name": "PEREZ GOMEZ ANA MARIA",
          "address": "Vereda El Silencio, finca La Esperanza",
          "municipality_code": "25053",
          "postal_code": "252007",
          "tax_responsibilities": [
           "R-99-PN"
          ]
         },
         "items": [
          {
           "description": "Leche cruda",
           "unit": "LTR",
           "quantity": "120",
           "unit_price": "1800"
          }
         ],
         "payment": {
          "form": "cash",
          "methods": [
           {
            "code": "10"
           }
          ]
         },
         "transmission": "per_operation",
         "adjustment_note": null,
         "totals": {
          "subtotal": "216000.00",
          "discounts": "0.00",
          "line_extension": "216000.00",
          "tax_exclusive": "0.00",
          "taxes": [],
          "allowances": "0.00",
          "charges": "0.00",
          "rounding": "0.00",
          "total": "216000.00",
          "withholdings": [],
          "prepayments": "0.00",
          "net_payable": null,
          "items": [
           {
            "gross": "216000.00",
            "discount": "0.00",
            "line_extension": "216000.00"
           }
          ]
         },
         "dian": {
          "status_code": "00",
          "message": "Procesado Correctamente.",
          "rules": []
         },
         "delivery": {
          "status": null,
          "pdf": false,
          "zip": false,
          "xml": true,
          "email": null
         },
         "created_at": "2026-10-23T09:15:02-05:00",
         "updated_at": "2026-10-23T09:15:03-05:00"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "202": {
      "description": "Versión 2026-10-22: la DIAN no contestó (`status: processing`; Trevol termina el documento y avisa por webhook; no crees otro documento para la misma venta, y si repites con la misma Idempotency-Key respondemos sin enviar) o el documento se está enviando (`status: sending`); también la contingencia (`status: contingency`). Lleva `Location` y, salvo la contingencia, `Retry-After: 30`. En 2026-10-21 la DIAN sin contestar es un 503 `dian_unavailable`.",
      "headers": {
       "Location": {
        "schema": {
         "type": "string"
        }
       },
       "Retry-After": {
        "schema": {
         "type": "integer"
        }
       },
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SupportDocument"
        }
       }
      }
     },
     "402": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "409": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "422": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        },
        "examples": {
         "sin_numeracion": {
          "summary": "No hay un rango de documento soporte vigente",
          "value": {
           "type": "https://platform.trevol.si/docs/errores#numbering_unavailable",
           "title": "La numeración no está disponible",
           "status": 422,
           "code": "numbering_unavailable",
           "detail": "La empresa no tiene una resolución de numeración activa en este ambiente.",
           "retryable": false,
           "reason": "no_resolution",
           "request_id": "req_5b1c5b1c5b1c5b1c5b1c5b1c"
          }
         }
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "429": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "503": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     }
    },
    "description": "Genera un **documento soporte** (tipo 05): el respaldo de una compra a quien no está obligado a facturar (una persona natural, un campesino, un proveedor del exterior). Trevol valida a fondo ANTES de reservar un número, numera con el rango de documento soporte vigente más nuevo (o el del prefijo de `numbering`), firma con el certificado de la empresa y lo manda a la DIAN. **Se genera, no se expide**: no hay PDF, ZIP ni correo; el XML y la respuesta de la DIAN se descargan en las dos versiones. La empresa necesita su software registrado ante la DIAN (`company_not_enabled` con `reason: missing_software`) y un rango vigente con números libres (`numbering_unavailable`, `no_resolution`). La `purchase_date` de cada línea no puede ser posterior a hoy (DSFC02b/c). Cuenta como documento de facturación en el cobro.\n\n**Respuestas.** `201` la DIAN lo validó (`status: accepted`). `202` solo en la versión 2026-10-22: la DIAN no contestó (`processing`), otra petición lo está enviando (`sending`) o, en habilitación, el set de pruebas todavía lo valida (`validating`, en las dos versiones); trae `Location` y `Retry-After`, y el resultado llega por GET y por webhook: **no crees otro documento para la misma operación**. `422` `validation_error` (se revisó a fondo ANTES de reservar: no se gastó el número, y `errors[]` dice el campo), `dian_rejected` (con `document` y las reglas traducidas; corrige con `PUT` y el mismo número), `company_not_enabled` o `numbering_unavailable` (con `reason`). `402` `insufficient_balance` (producción sin saldo: queda `pending` con su número). `409` `external_id_in_use` o `duplicate_document` (con `existing_id`). `503` `dian_unavailable` en la 2026-10-21. Pide `Idempotency-Key`: repetir la misma devuelve lo mismo sin enviar nada.",
    "tags": [
     "Documento soporte"
    ],
    "operationId": "createSupportDocument"
   },
   "get": {
    "summary": "Listar (documento soporte)",
    "parameters": [
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 100
      }
     },
     {
      "name": "starting_after",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "status",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "external_id",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "created_from",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "created_to",
      "in": "query",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "{object: list, data, has_more, next_cursor}",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "object",
          "data",
          "has_more",
          "next_cursor"
         ],
         "properties": {
          "object": {
           "type": "string",
           "enum": [
            "list"
           ]
          },
          "data": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/SupportDocument"
           }
          },
          "has_more": {
           "type": "boolean"
          },
          "next_cursor": {
           "type": [
            "string",
            "null"
           ]
          }
         }
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "Paginación por cursor (`limit` hasta 100, `starting_after`) y filtros `status`, `external_id`, `created_from` y `created_to`. `status=error` trae también los que están en verificación (`processing`).",
    "tags": [
     "Documento soporte"
    ],
    "operationId": "listSupportDocuments"
   }
  },
  "/support_documents/preview": {
   "post": {
    "summary": "Calcular un documento soporte sin emitirlo",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/SupportDocumentInput"
       },
       "examples": {
        "compra": {
         "summary": "Compra de leche a un campesino",
         "value": {
          "external_id": "OC-991",
          "seller": {
           "resident": true,
           "person_type": "natural",
           "document_type": "31",
           "document_number": "1020304050",
           "name": "PEREZ GOMEZ ANA MARIA",
           "address": "Vereda El Silencio, finca La Esperanza",
           "municipality_code": "25053",
           "postal_code": "252007",
           "tax_responsibilities": [
            "R-99-PN"
           ]
          },
          "items": [
           {
            "description": "Leche cruda",
            "unit": "LTR",
            "quantity": "120",
            "unit_price": "1800"
           }
          ],
          "payment": {
           "form": "cash",
           "methods": [
            {
             "code": "10"
            }
           ]
          },
          "notes": [
           "Compra de la semana 42 de octubre"
          ]
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Totales",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Preview"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "Valida y calcula los totales del documento soporte **sin** reservar un número ni enviar nada. No pide `Idempotency-Key` y no se cobra.",
    "tags": [
     "Documento soporte"
    ],
    "operationId": "previewSupportDocument"
   }
  },
  "/support_documents/{id}": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Un documento soporte",
    "responses": {
     "200": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SupportDocument"
        },
        "example": {
         "id": "sd_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
         "object": "support_document",
         "environment": "test",
         "status": "accepted",
         "number": "DS994001",
         "prefix": "DS",
         "external_id": "OC-991",
         "origin": "api",
         "cuds": "abababababababababababababababababababababababababababababababababababababababababababababababab",
         "qr": "https://catalogo-vpfe-hab.dian.gov.co/document/searchqr?documentkey=abababababababababababababababababababababababababababababababababababababababababababababababab",
         "issued_at": "2026-10-23T09:15:02-05:00",
         "seller": {
          "resident": true,
          "person_type": "natural",
          "document_type": "31",
          "document_number": "1020304050",
          "name": "PEREZ GOMEZ ANA MARIA",
          "address": "Vereda El Silencio, finca La Esperanza",
          "municipality_code": "25053",
          "postal_code": "252007",
          "tax_responsibilities": [
           "R-99-PN"
          ]
         },
         "items": [
          {
           "description": "Leche cruda",
           "unit": "LTR",
           "quantity": "120",
           "unit_price": "1800"
          }
         ],
         "payment": {
          "form": "cash",
          "methods": [
           {
            "code": "10"
           }
          ]
         },
         "transmission": "per_operation",
         "adjustment_note": null,
         "totals": {
          "subtotal": "216000.00",
          "discounts": "0.00",
          "line_extension": "216000.00",
          "tax_exclusive": "0.00",
          "taxes": [],
          "allowances": "0.00",
          "charges": "0.00",
          "rounding": "0.00",
          "total": "216000.00",
          "withholdings": [],
          "prepayments": "0.00",
          "net_payable": null,
          "items": [
           {
            "gross": "216000.00",
            "discount": "0.00",
            "line_extension": "216000.00"
           }
          ]
         },
         "dian": {
          "status_code": "00",
          "message": "Procesado Correctamente.",
          "rules": []
         },
         "delivery": {
          "status": null,
          "pdf": false,
          "zip": false,
          "xml": true,
          "email": null
         },
         "created_at": "2026-10-23T09:15:02-05:00",
         "updated_at": "2026-10-23T09:15:03-05:00"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "El documento soporte tal como se emitió: lo que mandaste, los totales, el CUDS y la respuesta de la DIAN. `delivery` no aplica (`status: null`).",
    "tags": [
     "Documento soporte"
    ],
    "operationId": "retrieveSupportDocument"
   },
   "put": {
    "summary": "Corregir un documento soporte rechazado (mismo número) y reenviarlo",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "required": true,
      "description": "Obligatoria: 1 a 255 caracteres ASCII visibles, única por pedido (7 días).",
      "schema": {
       "type": "string",
       "maxLength": 255
      }
     },
     {
      "name": "Trevol-Version",
      "in": "header",
      "required": false,
      "description": "La versión de la API. Si no viene, la de la llave (las llaves de antes quedan en 2026-10-21; las nuevas nacen en 2026-10-22).",
      "schema": {
       "type": "string",
       "enum": [
        "2026-10-21",
        "2026-10-22"
       ]
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/SupportDocumentInput"
       },
       "examples": {
        "compra": {
         "summary": "Compra de leche a un campesino",
         "value": {
          "external_id": "OC-991",
          "seller": {
           "resident": true,
           "person_type": "natural",
           "document_type": "31",
           "document_number": "1020304050",
           "name": "PEREZ GOMEZ ANA MARIA",
           "address": "Vereda El Silencio, finca La Esperanza",
           "municipality_code": "25053",
           "postal_code": "252007",
           "tax_responsibilities": [
            "R-99-PN"
           ]
          },
          "items": [
           {
            "description": "Leche cruda",
            "unit": "LTR",
            "quantity": "120",
            "unit_price": "1800"
           }
          ],
          "payment": {
           "form": "cash",
           "methods": [
            {
             "code": "10"
            }
           ]
          },
          "notes": [
           "Compra de la semana 42 de octubre"
          ]
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SupportDocument"
        },
        "example": {
         "id": "sd_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
         "object": "support_document",
         "environment": "test",
         "status": "accepted",
         "number": "DS994001",
         "prefix": "DS",
         "external_id": "OC-991",
         "origin": "api",
         "cuds": "abababababababababababababababababababababababababababababababababababababababababababababababab",
         "qr": "https://catalogo-vpfe-hab.dian.gov.co/document/searchqr?documentkey=abababababababababababababababababababababababababababababababababababababababababababababababab",
         "issued_at": "2026-10-23T09:15:02-05:00",
         "seller": {
          "resident": true,
          "person_type": "natural",
          "document_type": "31",
          "document_number": "1020304050",
          "name": "PEREZ GOMEZ ANA MARIA",
          "address": "Vereda El Silencio, finca La Esperanza",
          "municipality_code": "25053",
          "postal_code": "252007",
          "tax_responsibilities": [
           "R-99-PN"
          ]
         },
         "items": [
          {
           "description": "Leche cruda",
           "unit": "LTR",
           "quantity": "120",
           "unit_price": "1800"
          }
         ],
         "payment": {
          "form": "cash",
          "methods": [
           {
            "code": "10"
           }
          ]
         },
         "transmission": "per_operation",
         "adjustment_note": null,
         "totals": {
          "subtotal": "216000.00",
          "discounts": "0.00",
          "line_extension": "216000.00",
          "tax_exclusive": "0.00",
          "taxes": [],
          "allowances": "0.00",
          "charges": "0.00",
          "rounding": "0.00",
          "total": "216000.00",
          "withholdings": [],
          "prepayments": "0.00",
          "net_payable": null,
          "items": [
           {
            "gross": "216000.00",
            "discount": "0.00",
            "line_extension": "216000.00"
           }
          ]
         },
         "dian": {
          "status_code": "00",
          "message": "Procesado Correctamente.",
          "rules": []
         },
         "delivery": {
          "status": null,
          "pdf": false,
          "zip": false,
          "xml": true,
          "email": null
         },
         "created_at": "2026-10-23T09:15:02-05:00",
         "updated_at": "2026-10-23T09:15:03-05:00"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "202": {
      "description": "Versión 2026-10-22: la DIAN no contestó (`status: processing`; Trevol termina el documento y avisa por webhook; no crees otro documento para la misma venta, y si repites con la misma Idempotency-Key respondemos sin enviar) o el documento se está enviando (`status: sending`); también la contingencia (`status: contingency`). Lleva `Location` y, salvo la contingencia, `Retry-After: 30`. En 2026-10-21 la DIAN sin contestar es un 503 `dian_unavailable`.",
      "headers": {
       "Location": {
        "schema": {
         "type": "string"
        }
       },
       "Retry-After": {
        "schema": {
         "type": "integer"
        }
       },
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SupportDocument"
        }
       }
      }
     },
     "409": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     }
    },
    "description": "Corrige un documento soporte rechazado con el **mismo número** y lo vuelve a enviar.\n\nSolo si el documento está `rejected`, `error` o `pending`. Uno `accepted` no se corrige (se ajusta con una nota) y uno que la DIAN todavía verifica es `409 invalid_state`: espera el resultado. El `external_id` y la numeración no se cambian. Pide `Idempotency-Key`.",
    "tags": [
     "Documento soporte"
    ],
    "operationId": "correctSupportDocument"
   }
  },
  "/support_documents/{id}/send": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "post": {
    "summary": "Reenviar una pendiente o en error",
    "parameters": [
     {
      "name": "Trevol-Version",
      "in": "header",
      "required": false,
      "description": "La versión de la API. Si no viene, la de la llave (las llaves de antes quedan en 2026-10-21; las nuevas nacen en 2026-10-22).",
      "schema": {
       "type": "string",
       "enum": [
        "2026-10-21",
        "2026-10-22"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SupportDocument"
        },
        "example": {
         "id": "sd_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
         "object": "support_document",
         "environment": "test",
         "status": "accepted",
         "number": "DS994001",
         "prefix": "DS",
         "external_id": "OC-991",
         "origin": "api",
         "cuds": "abababababababababababababababababababababababababababababababababababababababababababababababab",
         "qr": "https://catalogo-vpfe-hab.dian.gov.co/document/searchqr?documentkey=abababababababababababababababababababababababababababababababababababababababababababababababab",
         "issued_at": "2026-10-23T09:15:02-05:00",
         "seller": {
          "resident": true,
          "person_type": "natural",
          "document_type": "31",
          "document_number": "1020304050",
          "name": "PEREZ GOMEZ ANA MARIA",
          "address": "Vereda El Silencio, finca La Esperanza",
          "municipality_code": "25053",
          "postal_code": "252007",
          "tax_responsibilities": [
           "R-99-PN"
          ]
         },
         "items": [
          {
           "description": "Leche cruda",
           "unit": "LTR",
           "quantity": "120",
           "unit_price": "1800"
          }
         ],
         "payment": {
          "form": "cash",
          "methods": [
           {
            "code": "10"
           }
          ]
         },
         "transmission": "per_operation",
         "adjustment_note": null,
         "totals": {
          "subtotal": "216000.00",
          "discounts": "0.00",
          "line_extension": "216000.00",
          "tax_exclusive": "0.00",
          "taxes": [],
          "allowances": "0.00",
          "charges": "0.00",
          "rounding": "0.00",
          "total": "216000.00",
          "withholdings": [],
          "prepayments": "0.00",
          "net_payable": null,
          "items": [
           {
            "gross": "216000.00",
            "discount": "0.00",
            "line_extension": "216000.00"
           }
          ]
         },
         "dian": {
          "status_code": "00",
          "message": "Procesado Correctamente.",
          "rules": []
         },
         "delivery": {
          "status": null,
          "pdf": false,
          "zip": false,
          "xml": true,
          "email": null
         },
         "created_at": "2026-10-23T09:15:02-05:00",
         "updated_at": "2026-10-23T09:15:03-05:00"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "202": {
      "description": "Versión 2026-10-22: la DIAN no contestó (`status: processing`; Trevol termina el documento y avisa por webhook; no crees otro documento para la misma venta, y si repites con la misma Idempotency-Key respondemos sin enviar) o el documento se está enviando (`status: sending`); también la contingencia (`status: contingency`). Lleva `Location` y, salvo la contingencia, `Retry-After: 30`. En 2026-10-21 la DIAN sin contestar es un 503 `dian_unavailable`.",
      "headers": {
       "Location": {
        "schema": {
         "type": "string"
        }
       },
       "Retry-After": {
        "schema": {
         "type": "integer"
        }
       },
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SupportDocument"
        }
       }
      }
     },
     "409": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "Vuelve a enviar un documento soporte `pending` o `error` (por ejemplo, después de recargar saldo).\n\nSin cuerpo. Con un documento `accepted` responde `200` con el documento tal cual; con uno que la DIAN todavía verifica no reenvía nada (`202`); con uno `rejected` es `409 invalid_state` (se corrige con `PUT`). No pide `Idempotency-Key` (reintentarlo es seguro).",
    "tags": [
     "Documento soporte"
    ],
    "operationId": "sendSupportDocument"
   }
  },
  "/support_documents/{id}/xml": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Archivo xml",
    "responses": {
     "200": {
      "description": "xml",
      "content": {
       "application/xml": {
        "schema": {
         "type": "string",
         "format": "binary"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "El XML firmado que se mandó a la DIAN (`application/xml`).",
    "tags": [
     "Documento soporte"
    ],
    "operationId": "downloadSupportDocumentXml"
   }
  },
  "/support_documents/{id}/dian_response": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Archivo dian_response",
    "responses": {
     "200": {
      "description": "dian_response",
      "content": {
       "application/xml": {
        "schema": {
         "type": "string",
         "format": "binary"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "El `ApplicationResponse` con que la DIAN contestó (`application/xml`), en las dos versiones.",
    "tags": [
     "Documento soporte"
    ],
    "operationId": "downloadSupportDocumentDianResponse"
   }
  },
  "/support_document_adjustments": {
   "post": {
    "summary": "Emitir una nota de ajuste del documento soporte",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "required": true,
      "description": "Obligatoria: 1 a 255 caracteres ASCII visibles, única por pedido (7 días).",
      "schema": {
       "type": "string",
       "maxLength": 255
      }
     },
     {
      "name": "Trevol-Version",
      "in": "header",
      "required": false,
      "description": "La versión de la API. Si no viene, la de la llave (las llaves de antes quedan en 2026-10-21; las nuevas nacen en 2026-10-22).",
      "schema": {
       "type": "string",
       "enum": [
        "2026-10-21",
        "2026-10-22"
       ]
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/SupportDocumentAdjustmentInput"
       },
       "examples": {
        "anulacion": {
         "summary": "Anulación de un documento soporte de Trevol",
         "value": {
          "external_id": "OC-991-ANULA",
          "concept": "2",
          "description": "Anulación: la compra de leche se registró dos veces en el ERP",
          "support_document": {
           "id": "sd_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
          },
          "items": [
           {
            "description": "Leche cruda",
            "unit": "LTR",
            "quantity": "120",
            "unit_price": "1800"
           }
          ]
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SupportDocumentAdjustment"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "202": {
      "description": "Versión 2026-10-22: la DIAN no contestó (`status: processing`; Trevol termina el documento y avisa por webhook; no crees otro documento para la misma venta, y si repites con la misma Idempotency-Key respondemos sin enviar) o el documento se está enviando (`status: sending`); también la contingencia (`status: contingency`). Lleva `Location` y, salvo la contingencia, `Retry-After: 30`. En 2026-10-21 la DIAN sin contestar es un 503 `dian_unavailable`.",
      "headers": {
       "Location": {
        "schema": {
         "type": "string"
        }
       },
       "Retry-After": {
        "schema": {
         "type": "integer"
        }
       },
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SupportDocumentAdjustment"
        }
       }
      }
     },
     "402": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "409": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "422": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "429": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "503": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     }
    },
    "description": "Genera la **nota de ajuste de un documento soporte** (95): corrige o anula una compra ya validada. El documento que ajusta es de Trevol (`support_document.id`) o de otra plataforma (`number`, `cuds`, `issue_date` y `total`). `concept` 1 a 5; el 2 anula y lleva exactamente los valores del documento. Sin `seller` hereda el del documento de Trevol. La suma de las notas no puede pasar del saldo del documento. Un documento soporte rechazado no se ajusta: se corrige con `PUT`.\n\n**Respuestas.** `201` la DIAN lo validó (`status: accepted`). `202` solo en la versión 2026-10-22: la DIAN no contestó (`processing`), otra petición lo está enviando (`sending`) o, en habilitación, el set de pruebas todavía lo valida (`validating`, en las dos versiones); trae `Location` y `Retry-After`, y el resultado llega por GET y por webhook: **no crees otro documento para la misma operación**. `422` `validation_error` (se revisó a fondo ANTES de reservar: no se gastó el número, y `errors[]` dice el campo), `dian_rejected` (con `document` y las reglas traducidas; corrige con `PUT` y el mismo número), `company_not_enabled` o `numbering_unavailable` (con `reason`). `402` `insufficient_balance` (producción sin saldo: queda `pending` con su número). `409` `external_id_in_use` o `duplicate_document` (con `existing_id`). `503` `dian_unavailable` en la 2026-10-21. Pide `Idempotency-Key`: repetir la misma devuelve lo mismo sin enviar nada.",
    "tags": [
     "Documento soporte"
    ],
    "operationId": "createSupportDocumentAdjustment"
   },
   "get": {
    "summary": "Listar (nota de ajuste del documento soporte)",
    "parameters": [
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 100
      }
     },
     {
      "name": "starting_after",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "status",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "external_id",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "created_from",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "created_to",
      "in": "query",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "{object: list, data, has_more, next_cursor}",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "object",
          "data",
          "has_more",
          "next_cursor"
         ],
         "properties": {
          "object": {
           "type": "string",
           "enum": [
            "list"
           ]
          },
          "data": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/SupportDocumentAdjustment"
           }
          },
          "has_more": {
           "type": "boolean"
          },
          "next_cursor": {
           "type": [
            "string",
            "null"
           ]
          }
         }
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "Paginación por cursor (`limit` hasta 100, `starting_after`) y filtros `status`, `external_id`, `created_from` y `created_to`. `status=error` trae también los que están en verificación (`processing`).",
    "tags": [
     "Documento soporte"
    ],
    "operationId": "listSupportDocumentAdjustments"
   }
  },
  "/support_document_adjustments/preview": {
   "post": {
    "summary": "Calcular una nota de ajuste del documento soporte sin emitirla",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/SupportDocumentAdjustmentInput"
       },
       "examples": {
        "anulacion": {
         "summary": "Anulación de un documento soporte de Trevol",
         "value": {
          "external_id": "OC-991-ANULA",
          "concept": "2",
          "description": "Anulación: la compra de leche se registró dos veces en el ERP",
          "support_document": {
           "id": "sd_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
          },
          "items": [
           {
            "description": "Leche cruda",
            "unit": "LTR",
            "quantity": "120",
            "unit_price": "1800"
           }
          ]
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Totales",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Preview"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "Valida y calcula la nota de ajuste **sin** reservar un número ni enviar nada.",
    "tags": [
     "Documento soporte"
    ],
    "operationId": "previewSupportDocumentAdjustment"
   }
  },
  "/support_document_adjustments/{id}": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Una nota de ajuste del documento soporte",
    "responses": {
     "200": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SupportDocumentAdjustment"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "La nota de ajuste del documento soporte, con `support_document` (el documento que ajusta).",
    "tags": [
     "Documento soporte"
    ],
    "operationId": "retrieveSupportDocumentAdjustment"
   },
   "put": {
    "summary": "Corregir una nota de ajuste del documento soporte rechazada (mismo número) y reenviarla",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "required": true,
      "description": "Obligatoria: 1 a 255 caracteres ASCII visibles, única por pedido (7 días).",
      "schema": {
       "type": "string",
       "maxLength": 255
      }
     },
     {
      "name": "Trevol-Version",
      "in": "header",
      "required": false,
      "description": "La versión de la API. Si no viene, la de la llave (las llaves de antes quedan en 2026-10-21; las nuevas nacen en 2026-10-22).",
      "schema": {
       "type": "string",
       "enum": [
        "2026-10-21",
        "2026-10-22"
       ]
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/SupportDocumentAdjustmentInput"
       },
       "examples": {
        "anulacion": {
         "summary": "Anulación de un documento soporte de Trevol",
         "value": {
          "external_id": "OC-991-ANULA",
          "concept": "2",
          "description": "Anulación: la compra de leche se registró dos veces en el ERP",
          "support_document": {
           "id": "sd_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
          },
          "items": [
           {
            "description": "Leche cruda",
            "unit": "LTR",
            "quantity": "120",
            "unit_price": "1800"
           }
          ]
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SupportDocumentAdjustment"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "202": {
      "description": "Versión 2026-10-22: la DIAN no contestó (`status: processing`; Trevol termina el documento y avisa por webhook; no crees otro documento para la misma venta, y si repites con la misma Idempotency-Key respondemos sin enviar) o el documento se está enviando (`status: sending`); también la contingencia (`status: contingency`). Lleva `Location` y, salvo la contingencia, `Retry-After: 30`. En 2026-10-21 la DIAN sin contestar es un 503 `dian_unavailable`.",
      "headers": {
       "Location": {
        "schema": {
         "type": "string"
        }
       },
       "Retry-After": {
        "schema": {
         "type": "integer"
        }
       },
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SupportDocumentAdjustment"
        }
       }
      }
     },
     "409": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     }
    },
    "description": "Corrige una nota de ajuste rechazada con el **mismo número** y la vuelve a enviar.\n\nSolo si el documento está `rejected`, `error` o `pending`. Uno `accepted` no se corrige (se ajusta con una nota) y uno que la DIAN todavía verifica es `409 invalid_state`: espera el resultado. El `external_id` y la numeración no se cambian. Pide `Idempotency-Key`.",
    "tags": [
     "Documento soporte"
    ],
    "operationId": "correctSupportDocumentAdjustment"
   }
  },
  "/support_document_adjustments/{id}/send": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "post": {
    "summary": "Reenviar una pendiente o en error",
    "parameters": [
     {
      "name": "Trevol-Version",
      "in": "header",
      "required": false,
      "description": "La versión de la API. Si no viene, la de la llave (las llaves de antes quedan en 2026-10-21; las nuevas nacen en 2026-10-22).",
      "schema": {
       "type": "string",
       "enum": [
        "2026-10-21",
        "2026-10-22"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SupportDocumentAdjustment"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "202": {
      "description": "Versión 2026-10-22: la DIAN no contestó (`status: processing`; Trevol termina el documento y avisa por webhook; no crees otro documento para la misma venta, y si repites con la misma Idempotency-Key respondemos sin enviar) o el documento se está enviando (`status: sending`); también la contingencia (`status: contingency`). Lleva `Location` y, salvo la contingencia, `Retry-After: 30`. En 2026-10-21 la DIAN sin contestar es un 503 `dian_unavailable`.",
      "headers": {
       "Location": {
        "schema": {
         "type": "string"
        }
       },
       "Retry-After": {
        "schema": {
         "type": "integer"
        }
       },
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SupportDocumentAdjustment"
        }
       }
      }
     },
     "409": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "Vuelve a enviar una nota de ajuste `pending` o `error`.\n\nSin cuerpo. Con un documento `accepted` responde `200` con el documento tal cual; con uno que la DIAN todavía verifica no reenvía nada (`202`); con uno `rejected` es `409 invalid_state` (se corrige con `PUT`). No pide `Idempotency-Key` (reintentarlo es seguro).",
    "tags": [
     "Documento soporte"
    ],
    "operationId": "sendSupportDocumentAdjustment"
   }
  },
  "/support_document_adjustments/{id}/xml": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Archivo xml",
    "responses": {
     "200": {
      "description": "xml",
      "content": {
       "application/xml": {
        "schema": {
         "type": "string",
         "format": "binary"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "El XML firmado que se mandó a la DIAN (`application/xml`).",
    "tags": [
     "Documento soporte"
    ],
    "operationId": "downloadSupportDocumentAdjustmentXml"
   }
  },
  "/support_document_adjustments/{id}/dian_response": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Archivo dian_response",
    "responses": {
     "200": {
      "description": "dian_response",
      "content": {
       "application/xml": {
        "schema": {
         "type": "string",
         "format": "binary"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "El `ApplicationResponse` con que la DIAN contestó (`application/xml`).",
    "tags": [
     "Documento soporte"
    ],
    "operationId": "downloadSupportDocumentAdjustmentDianResponse"
   }
  },
  "/equivalent_documents": {
   "post": {
    "summary": "Emitir un documento equivalente",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "required": true,
      "description": "Obligatoria: 1 a 255 caracteres ASCII visibles, única por pedido (7 días).",
      "schema": {
       "type": "string",
       "maxLength": 255
      }
     },
     {
      "name": "Trevol-Version",
      "in": "header",
      "required": false,
      "description": "La versión de la API. Si no viene, la de la llave (las llaves de antes quedan en 2026-10-21; las nuevas nacen en 2026-10-22).",
      "schema": {
       "type": "string",
       "enum": [
        "2026-10-21",
        "2026-10-22"
       ]
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/EquivalentDocumentInput"
       },
       "examples": {
        "pos": {
         "summary": "Tiquete POS de consumidor final, en la caja de un prefijo",
         "value": {
          "external_id": "TIQ-1",
          "customer": {
           "final_consumer": true
          },
          "pos": {
           "register": {
            "plate": "CJ-01",
            "location": "Local 1, Jamundí",
            "cashier": "PEREZ ANA",
            "type": "Caja principal"
           }
          },
          "numbering": {
           "prefix": "POS2"
          },
          "payment": {
           "form": "cash",
           "methods": [
            {
             "code": "10"
            }
           ]
          },
          "items": [
           {
            "description": "Gaseosa 400 ml",
            "code": "GAS-1",
            "unit": "94",
            "quantity": "2",
            "unit_price": "3000",
            "taxes": [
             {
              "code": "01",
              "rate": "19"
             }
            ]
           },
           {
            "description": "Almuerzo",
            "unit": "94",
            "quantity": "1",
            "unit_price": "18000"
           }
          ]
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/EquivalentDocument"
        },
        "example": {
         "id": "pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
         "object": "equivalent_document",
         "environment": "test",
         "status": "accepted",
         "number": "POS2994001",
         "prefix": "POS2",
         "external_id": "TIQ-1",
         "origin": "api",
         "cude": "abababababababababababababababababababababababababababababababababababababababababababababababab",
         "qr": "https://catalogo-vpfe-hab.dian.gov.co/document/searchqr?documentkey=abababababababababababababababababababababababababababababababababababababababababababababababab",
         "issued_at": "2026-10-23T09:15:02-05:00",
         "customer": {
          "final_consumer": true
         },
         "items": [
          {
           "description": "Gaseosa 400 ml",
           "code": "GAS-1",
           "unit": "94",
           "quantity": "2",
           "unit_price": "3000",
           "taxes": [
            {
             "code": "01",
             "rate": "19"
            }
           ]
          },
          {
           "description": "Almuerzo",
           "unit": "94",
           "quantity": "1",
           "unit_price": "18000"
          }
         ],
         "payment": {
          "form": "cash",
          "methods": [
           {
            "code": "10"
           }
          ]
         },
         "document_type": "20",
         "operation_type": "22",
         "pos": {
          "register": {
           "plate": "CJ-01",
           "location": "Local 1, Jamundí",
           "cashier": "PEREZ ANA",
           "type": "Caja principal"
          }
         },
         "contingency": null,
         "totals": {
          "subtotal": "24000.00",
          "discounts": "0.00",
          "line_extension": "24000.00",
          "tax_exclusive": "6000.00",
          "taxes": [
           {
            "code": "01",
            "name": "IVA",
            "rate": "19.00",
            "base": "6000.00",
            "amount": "1140.00"
           }
          ],
          "allowances": "0.00",
          "charges": "0.00",
          "rounding": "0.00",
          "total": "25140.00",
          "withholdings": [],
          "prepayments": "0.00",
          "net_payable": null,
          "items": [
           {
            "gross": "6000.00",
            "discount": "0.00",
            "line_extension": "6000.00"
           },
           {
            "gross": "18000.00",
            "discount": "0.00",
            "line_extension": "18000.00"
           }
          ]
         },
         "dian": {
          "status_code": "00",
          "message": "Procesado Correctamente.",
          "rules": []
         },
         "delivery": {
          "status": "pending",
          "pdf": false,
          "zip": false,
          "xml": true,
          "email": {
           "status": "pending",
           "to": null,
           "detail": null
          }
         },
         "created_at": "2026-10-23T09:15:02-05:00",
         "updated_at": "2026-10-23T09:15:03-05:00"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "202": {
      "description": "Versión 2026-10-22: la DIAN no contestó (`status: processing`; Trevol termina el documento y avisa por webhook; no crees otro documento para la misma venta, y si repites con la misma Idempotency-Key respondemos sin enviar) o el documento se está enviando (`status: sending`); también la contingencia (`status: contingency`). Lleva `Location` y, salvo la contingencia, `Retry-After: 30`. En 2026-10-21 la DIAN sin contestar es un 503 `dian_unavailable`.",
      "headers": {
       "Location": {
        "schema": {
         "type": "string"
        }
       },
       "Retry-After": {
        "schema": {
         "type": "integer"
        }
       },
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/EquivalentDocument"
        }
       }
      }
     },
     "402": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "409": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "422": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        },
        "examples": {
         "sin_numeracion": {
          "summary": "No hay una resolución POS vigente",
          "value": {
           "type": "https://platform.trevol.si/docs/errores#numbering_unavailable",
           "title": "La numeración no está disponible",
           "status": 422,
           "code": "numbering_unavailable",
           "detail": "La empresa no tiene una resolución de numeración activa en este ambiente.",
           "retryable": false,
           "reason": "no_resolution",
           "request_id": "req_5b1c5b1c5b1c5b1c5b1c5b1c"
          }
         }
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "429": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "503": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     }
    },
    "description": "Genera un **documento equivalente electrónico**: el tiquete POS (20, por defecto) o cualquiera de los otros nueve tipos de la tabla 16.3 (`document_type`: 25 cine, 27 espectáculos, 30 juegos, 35 transporte, 40 peajes, 45 extracto, 50 tiquete aéreo, 55 bolsa de valores, 60 servicios públicos; cada uno con su información propia en `extension`). El POS lleva su caja en `pos.register` y, si la empresa tiene varias cajas, el prefijo de su resolución en `numbering.prefix`. Se expide como la factura: PDF, ZIP y correo después del 201 (espera `equivalent_document.delivered` o consulta `delivery.status`). La contingencia 07 (documento físico) se pide con `contingency`; la 08 (la DIAN no contestó) la decide Trevol y responde `202` con `status: contingency`. En habilitación, el set de pruebas por tipo es automático: mientras la DIAN lo valida responde `202 validating` en las dos versiones y reintentar no vuelve a mandarlo. Cómo se calcula el CUDE del POS depende del despliegue del servicio, no de la empresa.\n\n**Respuestas.** `201` la DIAN lo validó (`status: accepted`). `202` solo en la versión 2026-10-22: la DIAN no contestó (`processing`), otra petición lo está enviando (`sending`) o, en habilitación, el set de pruebas todavía lo valida (`validating`, en las dos versiones); trae `Location` y `Retry-After`, y el resultado llega por GET y por webhook: **no crees otro documento para la misma operación**. `422` `validation_error` (se revisó a fondo ANTES de reservar: no se gastó el número, y `errors[]` dice el campo), `dian_rejected` (con `document` y las reglas traducidas; corrige con `PUT` y el mismo número), `company_not_enabled` o `numbering_unavailable` (con `reason`). `402` `insufficient_balance` (producción sin saldo: queda `pending` con su número). `409` `external_id_in_use` o `duplicate_document` (con `existing_id`). `503` `dian_unavailable` en la 2026-10-21. Pide `Idempotency-Key`: repetir la misma devuelve lo mismo sin enviar nada.",
    "tags": [
     "Documento equivalente"
    ],
    "operationId": "createEquivalentDocument"
   },
   "get": {
    "summary": "Listar (documento equivalente)",
    "parameters": [
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 100
      }
     },
     {
      "name": "starting_after",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "status",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "external_id",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "created_from",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "created_to",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "document_type",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "20",
        "25",
        "27",
        "30",
        "35",
        "40",
        "45",
        "50",
        "55",
        "60"
       ],
       "description": "Solo en documentos equivalentes: el tipo de la tabla 16.3 (el 32 de juegos se lee como 30)."
      }
     }
    ],
    "responses": {
     "200": {
      "description": "{object: list, data, has_more, next_cursor}",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "object",
          "data",
          "has_more",
          "next_cursor"
         ],
         "properties": {
          "object": {
           "type": "string",
           "enum": [
            "list"
           ]
          },
          "data": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/EquivalentDocument"
           }
          },
          "has_more": {
           "type": "boolean"
          },
          "next_cursor": {
           "type": [
            "string",
            "null"
           ]
          }
         }
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "Paginación por cursor (`limit` hasta 100, `starting_after`) y filtros `status`, `external_id`, `created_from` y `created_to`. `status=error` trae también los que están en verificación (`processing`). Además, `document_type` filtra por tipo.",
    "tags": [
     "Documento equivalente"
    ],
    "operationId": "listEquivalentDocuments"
   }
  },
  "/equivalent_documents/preview": {
   "post": {
    "summary": "Calcular un documento equivalente sin emitirlo",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/EquivalentDocumentInput"
       },
       "examples": {
        "pos": {
         "summary": "Tiquete POS de consumidor final, en la caja de un prefijo",
         "value": {
          "external_id": "TIQ-1",
          "customer": {
           "final_consumer": true
          },
          "pos": {
           "register": {
            "plate": "CJ-01",
            "location": "Local 1, Jamundí",
            "cashier": "PEREZ ANA",
            "type": "Caja principal"
           }
          },
          "numbering": {
           "prefix": "POS2"
          },
          "payment": {
           "form": "cash",
           "methods": [
            {
             "code": "10"
            }
           ]
          },
          "items": [
           {
            "description": "Gaseosa 400 ml",
            "code": "GAS-1",
            "unit": "94",
            "quantity": "2",
            "unit_price": "3000",
            "taxes": [
             {
              "code": "01",
              "rate": "19"
             }
            ]
           },
           {
            "description": "Almuerzo",
            "unit": "94",
            "quantity": "1",
            "unit_price": "18000"
           }
          ]
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Totales",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Preview"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "Valida y calcula los totales **sin** reservar un número ni enviar nada. No pide `Idempotency-Key`.",
    "tags": [
     "Documento equivalente"
    ],
    "operationId": "previewEquivalentDocument"
   }
  },
  "/equivalent_documents/{id}": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Un documento equivalente",
    "responses": {
     "200": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/EquivalentDocument"
        },
        "example": {
         "id": "pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
         "object": "equivalent_document",
         "environment": "test",
         "status": "accepted",
         "number": "POS2994001",
         "prefix": "POS2",
         "external_id": "TIQ-1",
         "origin": "api",
         "cude": "abababababababababababababababababababababababababababababababababababababababababababababababab",
         "qr": "https://catalogo-vpfe-hab.dian.gov.co/document/searchqr?documentkey=abababababababababababababababababababababababababababababababababababababababababababababababab",
         "issued_at": "2026-10-23T09:15:02-05:00",
         "customer": {
          "final_consumer": true
         },
         "items": [
          {
           "description": "Gaseosa 400 ml",
           "code": "GAS-1",
           "unit": "94",
           "quantity": "2",
           "unit_price": "3000",
           "taxes": [
            {
             "code": "01",
             "rate": "19"
            }
           ]
          },
          {
           "description": "Almuerzo",
           "unit": "94",
           "quantity": "1",
           "unit_price": "18000"
          }
         ],
         "payment": {
          "form": "cash",
          "methods": [
           {
            "code": "10"
           }
          ]
         },
         "document_type": "20",
         "operation_type": "22",
         "pos": {
          "register": {
           "plate": "CJ-01",
           "location": "Local 1, Jamundí",
           "cashier": "PEREZ ANA",
           "type": "Caja principal"
          }
         },
         "contingency": null,
         "totals": {
          "subtotal": "24000.00",
          "discounts": "0.00",
          "line_extension": "24000.00",
          "tax_exclusive": "6000.00",
          "taxes": [
           {
            "code": "01",
            "name": "IVA",
            "rate": "19.00",
            "base": "6000.00",
            "amount": "1140.00"
           }
          ],
          "allowances": "0.00",
          "charges": "0.00",
          "rounding": "0.00",
          "total": "25140.00",
          "withholdings": [],
          "prepayments": "0.00",
          "net_payable": null,
          "items": [
           {
            "gross": "6000.00",
            "discount": "0.00",
            "line_extension": "6000.00"
           },
           {
            "gross": "18000.00",
            "discount": "0.00",
            "line_extension": "18000.00"
           }
          ]
         },
         "dian": {
          "status_code": "00",
          "message": "Procesado Correctamente.",
          "rules": []
         },
         "delivery": {
          "status": "pending",
          "pdf": false,
          "zip": false,
          "xml": true,
          "email": {
           "status": "pending",
           "to": null,
           "detail": null
          }
         },
         "created_at": "2026-10-23T09:15:02-05:00",
         "updated_at": "2026-10-23T09:15:03-05:00"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "El documento equivalente tal como se emitió. `contingency` dice si salió en contingencia (07 u 08) y, en la 08, cuándo se mandó el respaldo POS.",
    "tags": [
     "Documento equivalente"
    ],
    "operationId": "retrieveEquivalentDocument"
   },
   "put": {
    "summary": "Corregir un documento equivalente rechazado (mismo número) y reenviarlo",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "required": true,
      "description": "Obligatoria: 1 a 255 caracteres ASCII visibles, única por pedido (7 días).",
      "schema": {
       "type": "string",
       "maxLength": 255
      }
     },
     {
      "name": "Trevol-Version",
      "in": "header",
      "required": false,
      "description": "La versión de la API. Si no viene, la de la llave (las llaves de antes quedan en 2026-10-21; las nuevas nacen en 2026-10-22).",
      "schema": {
       "type": "string",
       "enum": [
        "2026-10-21",
        "2026-10-22"
       ]
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/EquivalentDocumentInput"
       },
       "examples": {
        "pos": {
         "summary": "Tiquete POS de consumidor final, en la caja de un prefijo",
         "value": {
          "external_id": "TIQ-1",
          "customer": {
           "final_consumer": true
          },
          "pos": {
           "register": {
            "plate": "CJ-01",
            "location": "Local 1, Jamundí",
            "cashier": "PEREZ ANA",
            "type": "Caja principal"
           }
          },
          "numbering": {
           "prefix": "POS2"
          },
          "payment": {
           "form": "cash",
           "methods": [
            {
             "code": "10"
            }
           ]
          },
          "items": [
           {
            "description": "Gaseosa 400 ml",
            "code": "GAS-1",
            "unit": "94",
            "quantity": "2",
            "unit_price": "3000",
            "taxes": [
             {
              "code": "01",
              "rate": "19"
             }
            ]
           },
           {
            "description": "Almuerzo",
            "unit": "94",
            "quantity": "1",
            "unit_price": "18000"
           }
          ]
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/EquivalentDocument"
        },
        "example": {
         "id": "pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
         "object": "equivalent_document",
         "environment": "test",
         "status": "accepted",
         "number": "POS2994001",
         "prefix": "POS2",
         "external_id": "TIQ-1",
         "origin": "api",
         "cude": "abababababababababababababababababababababababababababababababababababababababababababababababab",
         "qr": "https://catalogo-vpfe-hab.dian.gov.co/document/searchqr?documentkey=abababababababababababababababababababababababababababababababababababababababababababababababab",
         "issued_at": "2026-10-23T09:15:02-05:00",
         "customer": {
          "final_consumer": true
         },
         "items": [
          {
           "description": "Gaseosa 400 ml",
           "code": "GAS-1",
           "unit": "94",
           "quantity": "2",
           "unit_price": "3000",
           "taxes": [
            {
             "code": "01",
             "rate": "19"
            }
           ]
          },
          {
           "description": "Almuerzo",
           "unit": "94",
           "quantity": "1",
           "unit_price": "18000"
          }
         ],
         "payment": {
          "form": "cash",
          "methods": [
           {
            "code": "10"
           }
          ]
         },
         "document_type": "20",
         "operation_type": "22",
         "pos": {
          "register": {
           "plate": "CJ-01",
           "location": "Local 1, Jamundí",
           "cashier": "PEREZ ANA",
           "type": "Caja principal"
          }
         },
         "contingency": null,
         "totals": {
          "subtotal": "24000.00",
          "discounts": "0.00",
          "line_extension": "24000.00",
          "tax_exclusive": "6000.00",
          "taxes": [
           {
            "code": "01",
            "name": "IVA",
            "rate": "19.00",
            "base": "6000.00",
            "amount": "1140.00"
           }
          ],
          "allowances": "0.00",
          "charges": "0.00",
          "rounding": "0.00",
          "total": "25140.00",
          "withholdings": [],
          "prepayments": "0.00",
          "net_payable": null,
          "items": [
           {
            "gross": "6000.00",
            "discount": "0.00",
            "line_extension": "6000.00"
           },
           {
            "gross": "18000.00",
            "discount": "0.00",
            "line_extension": "18000.00"
           }
          ]
         },
         "dian": {
          "status_code": "00",
          "message": "Procesado Correctamente.",
          "rules": []
         },
         "delivery": {
          "status": "pending",
          "pdf": false,
          "zip": false,
          "xml": true,
          "email": {
           "status": "pending",
           "to": null,
           "detail": null
          }
         },
         "created_at": "2026-10-23T09:15:02-05:00",
         "updated_at": "2026-10-23T09:15:03-05:00"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "202": {
      "description": "Versión 2026-10-22: la DIAN no contestó (`status: processing`; Trevol termina el documento y avisa por webhook; no crees otro documento para la misma venta, y si repites con la misma Idempotency-Key respondemos sin enviar) o el documento se está enviando (`status: sending`); también la contingencia (`status: contingency`). Lleva `Location` y, salvo la contingencia, `Retry-After: 30`. En 2026-10-21 la DIAN sin contestar es un 503 `dian_unavailable`.",
      "headers": {
       "Location": {
        "schema": {
         "type": "string"
        }
       },
       "Retry-After": {
        "schema": {
         "type": "integer"
        }
       },
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/EquivalentDocument"
        }
       }
      }
     },
     "409": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     }
    },
    "description": "Corrige un documento equivalente rechazado con el **mismo número** y lo vuelve a enviar. Con el set de pruebas en curso responde `409 invalid_state`.\n\nSolo si el documento está `rejected`, `error` o `pending`. Uno `accepted` no se corrige (se ajusta con una nota) y uno que la DIAN todavía verifica es `409 invalid_state`: espera el resultado. El `external_id` y la numeración no se cambian. Pide `Idempotency-Key`.",
    "tags": [
     "Documento equivalente"
    ],
    "operationId": "correctEquivalentDocument"
   }
  },
  "/equivalent_documents/{id}/send": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "post": {
    "summary": "Reenviar una pendiente o en error",
    "parameters": [
     {
      "name": "Trevol-Version",
      "in": "header",
      "required": false,
      "description": "La versión de la API. Si no viene, la de la llave (las llaves de antes quedan en 2026-10-21; las nuevas nacen en 2026-10-22).",
      "schema": {
       "type": "string",
       "enum": [
        "2026-10-21",
        "2026-10-22"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/EquivalentDocument"
        },
        "example": {
         "id": "pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
         "object": "equivalent_document",
         "environment": "test",
         "status": "accepted",
         "number": "POS2994001",
         "prefix": "POS2",
         "external_id": "TIQ-1",
         "origin": "api",
         "cude": "abababababababababababababababababababababababababababababababababababababababababababababababab",
         "qr": "https://catalogo-vpfe-hab.dian.gov.co/document/searchqr?documentkey=abababababababababababababababababababababababababababababababababababababababababababababababab",
         "issued_at": "2026-10-23T09:15:02-05:00",
         "customer": {
          "final_consumer": true
         },
         "items": [
          {
           "description": "Gaseosa 400 ml",
           "code": "GAS-1",
           "unit": "94",
           "quantity": "2",
           "unit_price": "3000",
           "taxes": [
            {
             "code": "01",
             "rate": "19"
            }
           ]
          },
          {
           "description": "Almuerzo",
           "unit": "94",
           "quantity": "1",
           "unit_price": "18000"
          }
         ],
         "payment": {
          "form": "cash",
          "methods": [
           {
            "code": "10"
           }
          ]
         },
         "document_type": "20",
         "operation_type": "22",
         "pos": {
          "register": {
           "plate": "CJ-01",
           "location": "Local 1, Jamundí",
           "cashier": "PEREZ ANA",
           "type": "Caja principal"
          }
         },
         "contingency": null,
         "totals": {
          "subtotal": "24000.00",
          "discounts": "0.00",
          "line_extension": "24000.00",
          "tax_exclusive": "6000.00",
          "taxes": [
           {
            "code": "01",
            "name": "IVA",
            "rate": "19.00",
            "base": "6000.00",
            "amount": "1140.00"
           }
          ],
          "allowances": "0.00",
          "charges": "0.00",
          "rounding": "0.00",
          "total": "25140.00",
          "withholdings": [],
          "prepayments": "0.00",
          "net_payable": null,
          "items": [
           {
            "gross": "6000.00",
            "discount": "0.00",
            "line_extension": "6000.00"
           },
           {
            "gross": "18000.00",
            "discount": "0.00",
            "line_extension": "18000.00"
           }
          ]
         },
         "dian": {
          "status_code": "00",
          "message": "Procesado Correctamente.",
          "rules": []
         },
         "delivery": {
          "status": "pending",
          "pdf": false,
          "zip": false,
          "xml": true,
          "email": {
           "status": "pending",
           "to": null,
           "detail": null
          }
         },
         "created_at": "2026-10-23T09:15:02-05:00",
         "updated_at": "2026-10-23T09:15:03-05:00"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "202": {
      "description": "Versión 2026-10-22: la DIAN no contestó (`status: processing`; Trevol termina el documento y avisa por webhook; no crees otro documento para la misma venta, y si repites con la misma Idempotency-Key respondemos sin enviar) o el documento se está enviando (`status: sending`); también la contingencia (`status: contingency`). Lleva `Location` y, salvo la contingencia, `Retry-After: 30`. En 2026-10-21 la DIAN sin contestar es un 503 `dian_unavailable`.",
      "headers": {
       "Location": {
        "schema": {
         "type": "string"
        }
       },
       "Retry-After": {
        "schema": {
         "type": "integer"
        }
       },
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/EquivalentDocument"
        }
       }
      }
     },
     "409": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "Vuelve a enviar un documento equivalente `pending` o `error`. En contingencia devuelve el documento (lo reenvía Trevol). Con el set de pruebas en curso (`validating`) solo consulta: no lo vuelve a mandar.\n\nSin cuerpo. Con un documento `accepted` responde `200` con el documento tal cual; con uno que la DIAN todavía verifica no reenvía nada (`202`); con uno `rejected` es `409 invalid_state` (se corrige con `PUT`). No pide `Idempotency-Key` (reintentarlo es seguro).",
    "tags": [
     "Documento equivalente"
    ],
    "operationId": "sendEquivalentDocument"
   }
  },
  "/equivalent_documents/{id}/pdf": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Archivo pdf",
    "responses": {
     "200": {
      "description": "pdf",
      "content": {
       "application/pdf": {
        "schema": {
         "type": "string",
         "format": "binary"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "La representación gráfica (`application/pdf`). Si todavía no se hizo, se genera en el momento.",
    "tags": [
     "Documento equivalente"
    ],
    "operationId": "downloadEquivalentDocumentPdf"
   }
  },
  "/equivalent_documents/{id}/xml": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Archivo xml",
    "responses": {
     "200": {
      "description": "xml",
      "content": {
       "application/xml": {
        "schema": {
         "type": "string",
         "format": "binary"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "El XML firmado que se mandó a la DIAN (`application/xml`).",
    "tags": [
     "Documento equivalente"
    ],
    "operationId": "downloadEquivalentDocumentXml"
   }
  },
  "/equivalent_documents/{id}/zip": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Archivo zip",
    "responses": {
     "200": {
      "description": "zip",
      "content": {
       "application/zip": {
        "schema": {
         "type": "string",
         "format": "binary"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "El ZIP de entrega con el XML firmado y el PDF (`application/zip`).",
    "tags": [
     "Documento equivalente"
    ],
    "operationId": "downloadEquivalentDocumentZip"
   }
  },
  "/equivalent_documents/{id}/dian_response": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Archivo dian_response",
    "responses": {
     "200": {
      "description": "dian_response",
      "content": {
       "application/xml": {
        "schema": {
         "type": "string",
         "format": "binary"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "El `ApplicationResponse` con que la DIAN contestó (`application/xml`).",
    "tags": [
     "Documento equivalente"
    ],
    "operationId": "downloadEquivalentDocumentDianResponse"
   }
  },
  "/equivalent_document_adjustments": {
   "post": {
    "summary": "Emitir una nota de ajuste del documento equivalente",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "required": true,
      "description": "Obligatoria: 1 a 255 caracteres ASCII visibles, única por pedido (7 días).",
      "schema": {
       "type": "string",
       "maxLength": 255
      }
     },
     {
      "name": "Trevol-Version",
      "in": "header",
      "required": false,
      "description": "La versión de la API. Si no viene, la de la llave (las llaves de antes quedan en 2026-10-21; las nuevas nacen en 2026-10-22).",
      "schema": {
       "type": "string",
       "enum": [
        "2026-10-21",
        "2026-10-22"
       ]
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/EquivalentDocumentAdjustmentInput"
       },
       "examples": {
        "devolucion": {
         "summary": "Nota crédito: una devolución",
         "value": {
          "external_id": "TIQ-1-DEV",
          "note_type": "credit",
          "concept": "1",
          "equivalent_document": {
           "id": "pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
          },
          "items": [
           {
            "description": "Devolución gaseosa",
            "unit": "94",
            "quantity": "1",
            "unit_price": "3000",
            "taxes": [
             {
              "code": "01",
              "rate": "19"
             }
            ]
           }
          ]
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/EquivalentDocumentAdjustment"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "202": {
      "description": "Versión 2026-10-22: la DIAN no contestó (`status: processing`; Trevol termina el documento y avisa por webhook; no crees otro documento para la misma venta, y si repites con la misma Idempotency-Key respondemos sin enviar) o el documento se está enviando (`status: sending`); también la contingencia (`status: contingency`). Lleva `Location` y, salvo la contingencia, `Retry-After: 30`. En 2026-10-21 la DIAN sin contestar es un 503 `dian_unavailable`.",
      "headers": {
       "Location": {
        "schema": {
         "type": "string"
        }
       },
       "Retry-After": {
        "schema": {
         "type": "integer"
        }
       },
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/EquivalentDocumentAdjustment"
        }
       }
      }
     },
     "402": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "409": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "422": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "429": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "503": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     }
    },
    "description": "Genera la **nota de ajuste de un documento equivalente**: crédito (94) o débito (93) según `note_type`. El documento que ajusta es de Trevol (`equivalent_document.id`) o de otra plataforma. `concept` 1 a 5 (el 2 anula y lleva exactamente los valores del documento). Sin `customer` toma el del documento; en juegos el adquirente es la DIAN. Se expide como el documento: PDF, ZIP y correo.\n\n**Respuestas.** `201` la DIAN lo validó (`status: accepted`). `202` solo en la versión 2026-10-22: la DIAN no contestó (`processing`), otra petición lo está enviando (`sending`) o, en habilitación, el set de pruebas todavía lo valida (`validating`, en las dos versiones); trae `Location` y `Retry-After`, y el resultado llega por GET y por webhook: **no crees otro documento para la misma operación**. `422` `validation_error` (se revisó a fondo ANTES de reservar: no se gastó el número, y `errors[]` dice el campo), `dian_rejected` (con `document` y las reglas traducidas; corrige con `PUT` y el mismo número), `company_not_enabled` o `numbering_unavailable` (con `reason`). `402` `insufficient_balance` (producción sin saldo: queda `pending` con su número). `409` `external_id_in_use` o `duplicate_document` (con `existing_id`). `503` `dian_unavailable` en la 2026-10-21. Pide `Idempotency-Key`: repetir la misma devuelve lo mismo sin enviar nada.",
    "tags": [
     "Documento equivalente"
    ],
    "operationId": "createEquivalentDocumentAdjustment"
   },
   "get": {
    "summary": "Listar (nota de ajuste del documento equivalente)",
    "parameters": [
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 100
      }
     },
     {
      "name": "starting_after",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "status",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "external_id",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "created_from",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "created_to",
      "in": "query",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "{object: list, data, has_more, next_cursor}",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "object",
          "data",
          "has_more",
          "next_cursor"
         ],
         "properties": {
          "object": {
           "type": "string",
           "enum": [
            "list"
           ]
          },
          "data": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/EquivalentDocumentAdjustment"
           }
          },
          "has_more": {
           "type": "boolean"
          },
          "next_cursor": {
           "type": [
            "string",
            "null"
           ]
          }
         }
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "Paginación por cursor (`limit` hasta 100, `starting_after`) y filtros `status`, `external_id`, `created_from` y `created_to`. `status=error` trae también los que están en verificación (`processing`).",
    "tags": [
     "Documento equivalente"
    ],
    "operationId": "listEquivalentDocumentAdjustments"
   }
  },
  "/equivalent_document_adjustments/preview": {
   "post": {
    "summary": "Calcular una nota de ajuste del documento equivalente sin emitirla",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/EquivalentDocumentAdjustmentInput"
       },
       "examples": {
        "devolucion": {
         "summary": "Nota crédito: una devolución",
         "value": {
          "external_id": "TIQ-1-DEV",
          "note_type": "credit",
          "concept": "1",
          "equivalent_document": {
           "id": "pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
          },
          "items": [
           {
            "description": "Devolución gaseosa",
            "unit": "94",
            "quantity": "1",
            "unit_price": "3000",
            "taxes": [
             {
              "code": "01",
              "rate": "19"
             }
            ]
           }
          ]
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Totales",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Preview"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "Valida y calcula la nota de ajuste **sin** reservar un número ni enviar nada.",
    "tags": [
     "Documento equivalente"
    ],
    "operationId": "previewEquivalentDocumentAdjustment"
   }
  },
  "/equivalent_document_adjustments/{id}": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Una nota de ajuste del documento equivalente",
    "responses": {
     "200": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/EquivalentDocumentAdjustment"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "La nota de ajuste del documento equivalente, con `equivalent_document` (el documento que ajusta).",
    "tags": [
     "Documento equivalente"
    ],
    "operationId": "retrieveEquivalentDocumentAdjustment"
   },
   "put": {
    "summary": "Corregir una nota de ajuste del documento equivalente rechazada (mismo número) y reenviarla",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "required": true,
      "description": "Obligatoria: 1 a 255 caracteres ASCII visibles, única por pedido (7 días).",
      "schema": {
       "type": "string",
       "maxLength": 255
      }
     },
     {
      "name": "Trevol-Version",
      "in": "header",
      "required": false,
      "description": "La versión de la API. Si no viene, la de la llave (las llaves de antes quedan en 2026-10-21; las nuevas nacen en 2026-10-22).",
      "schema": {
       "type": "string",
       "enum": [
        "2026-10-21",
        "2026-10-22"
       ]
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/EquivalentDocumentAdjustmentInput"
       },
       "examples": {
        "devolucion": {
         "summary": "Nota crédito: una devolución",
         "value": {
          "external_id": "TIQ-1-DEV",
          "note_type": "credit",
          "concept": "1",
          "equivalent_document": {
           "id": "pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
          },
          "items": [
           {
            "description": "Devolución gaseosa",
            "unit": "94",
            "quantity": "1",
            "unit_price": "3000",
            "taxes": [
             {
              "code": "01",
              "rate": "19"
             }
            ]
           }
          ]
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/EquivalentDocumentAdjustment"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "202": {
      "description": "Versión 2026-10-22: la DIAN no contestó (`status: processing`; Trevol termina el documento y avisa por webhook; no crees otro documento para la misma venta, y si repites con la misma Idempotency-Key respondemos sin enviar) o el documento se está enviando (`status: sending`); también la contingencia (`status: contingency`). Lleva `Location` y, salvo la contingencia, `Retry-After: 30`. En 2026-10-21 la DIAN sin contestar es un 503 `dian_unavailable`.",
      "headers": {
       "Location": {
        "schema": {
         "type": "string"
        }
       },
       "Retry-After": {
        "schema": {
         "type": "integer"
        }
       },
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/EquivalentDocumentAdjustment"
        }
       }
      }
     },
     "409": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     }
    },
    "description": "Corrige una nota de ajuste rechazada con el **mismo número** y la vuelve a enviar.\n\nSolo si el documento está `rejected`, `error` o `pending`. Uno `accepted` no se corrige (se ajusta con una nota) y uno que la DIAN todavía verifica es `409 invalid_state`: espera el resultado. El `external_id` y la numeración no se cambian. Pide `Idempotency-Key`.",
    "tags": [
     "Documento equivalente"
    ],
    "operationId": "correctEquivalentDocumentAdjustment"
   }
  },
  "/equivalent_document_adjustments/{id}/send": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "post": {
    "summary": "Reenviar una pendiente o en error",
    "parameters": [
     {
      "name": "Trevol-Version",
      "in": "header",
      "required": false,
      "description": "La versión de la API. Si no viene, la de la llave (las llaves de antes quedan en 2026-10-21; las nuevas nacen en 2026-10-22).",
      "schema": {
       "type": "string",
       "enum": [
        "2026-10-21",
        "2026-10-22"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/EquivalentDocumentAdjustment"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "202": {
      "description": "Versión 2026-10-22: la DIAN no contestó (`status: processing`; Trevol termina el documento y avisa por webhook; no crees otro documento para la misma venta, y si repites con la misma Idempotency-Key respondemos sin enviar) o el documento se está enviando (`status: sending`); también la contingencia (`status: contingency`). Lleva `Location` y, salvo la contingencia, `Retry-After: 30`. En 2026-10-21 la DIAN sin contestar es un 503 `dian_unavailable`.",
      "headers": {
       "Location": {
        "schema": {
         "type": "string"
        }
       },
       "Retry-After": {
        "schema": {
         "type": "integer"
        }
       },
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/EquivalentDocumentAdjustment"
        }
       }
      }
     },
     "409": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "Vuelve a enviar una nota de ajuste `pending` o `error`.\n\nSin cuerpo. Con un documento `accepted` responde `200` con el documento tal cual; con uno que la DIAN todavía verifica no reenvía nada (`202`); con uno `rejected` es `409 invalid_state` (se corrige con `PUT`). No pide `Idempotency-Key` (reintentarlo es seguro).",
    "tags": [
     "Documento equivalente"
    ],
    "operationId": "sendEquivalentDocumentAdjustment"
   }
  },
  "/equivalent_document_adjustments/{id}/pdf": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Archivo pdf",
    "responses": {
     "200": {
      "description": "pdf",
      "content": {
       "application/pdf": {
        "schema": {
         "type": "string",
         "format": "binary"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "La representación gráfica (`application/pdf`).",
    "tags": [
     "Documento equivalente"
    ],
    "operationId": "downloadEquivalentDocumentAdjustmentPdf"
   }
  },
  "/equivalent_document_adjustments/{id}/xml": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Archivo xml",
    "responses": {
     "200": {
      "description": "xml",
      "content": {
       "application/xml": {
        "schema": {
         "type": "string",
         "format": "binary"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "El XML firmado que se mandó a la DIAN (`application/xml`).",
    "tags": [
     "Documento equivalente"
    ],
    "operationId": "downloadEquivalentDocumentAdjustmentXml"
   }
  },
  "/equivalent_document_adjustments/{id}/zip": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Archivo zip",
    "responses": {
     "200": {
      "description": "zip",
      "content": {
       "application/zip": {
        "schema": {
         "type": "string",
         "format": "binary"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "El ZIP de entrega (`application/zip`).",
    "tags": [
     "Documento equivalente"
    ],
    "operationId": "downloadEquivalentDocumentAdjustmentZip"
   }
  },
  "/equivalent_document_adjustments/{id}/dian_response": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Archivo dian_response",
    "responses": {
     "200": {
      "description": "dian_response",
      "content": {
       "application/xml": {
        "schema": {
         "type": "string",
         "format": "binary"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "El `ApplicationResponse` con que la DIAN contestó (`application/xml`).",
    "tags": [
     "Documento equivalente"
    ],
    "operationId": "downloadEquivalentDocumentAdjustmentDianResponse"
   }
  },
  "/payrolls": {
   "post": {
    "summary": "Emitir una nómina electrónica",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "required": true,
      "description": "Obligatoria: 1 a 255 caracteres ASCII visibles, única por pedido (7 días).",
      "schema": {
       "type": "string",
       "maxLength": 255
      }
     },
     {
      "name": "Trevol-Version",
      "in": "header",
      "required": false,
      "description": "La versión de la API. Si no viene, la de la llave (las llaves de antes quedan en 2026-10-21; las nuevas nacen en 2026-10-22).",
      "schema": {
       "type": "string",
       "enum": [
        "2026-10-21",
        "2026-10-22"
       ]
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/PayrollInput"
       },
       "examples": {
        "mensual": {
         "summary": "Nómina de un mes completo",
         "value": {
          "external_id": "NOM-2026-09-001",
          "period": {
           "hire_date": "2024-03-01",
           "start": "2026-09-01",
           "end": "2026-09-30"
          },
          "pay_period": "5",
          "notes": [
           "Nómina de septiembre de 2026"
          ],
          "employee": {
           "type": "01",
           "subtype": "00",
           "high_risk_pension": false,
           "document_type": "13",
           "document_number": "1000000101",
           "first_surname": "PRUEBA",
           "second_surname": "NOMINA01",
           "first_name": "TRABAJADOR",
           "other_names": "DE PRUEBA",
           "workplace": {
            "country": "CO",
            "municipality_code": "76001",
            "address": "Calle 1 # 1-1"
           },
           "integral_salary": false,
           "contract_type": "2",
           "salary": "1423500",
           "code": "TRAB-01"
          },
          "payment": {
           "form": "1",
           "method": "42",
           "bank": "Banco de Pruebas",
           "account_type": "Ahorros",
           "account_number": "0001234501"
          },
          "payment_dates": [
           "2026-09-30"
          ],
          "earnings": {
           "basic": {
            "days": 30,
            "amount": "1423500"
           },
           "transport": [
            {
             "allowance": "200000"
            }
           ]
          },
          "deductions": {
           "health": {
            "percent": "4",
            "amount": "56940"
           },
           "pension": {
            "percent": "4",
            "amount": "56940"
           }
          }
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Payroll"
        },
        "example": {
         "id": "pr_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
         "object": "payroll",
         "environment": "live",
         "status": "accepted",
         "number": "NE15",
         "prefix": "NE",
         "external_id": "NOM-2026-09-001",
         "origin": "api",
         "cune": "abababababababababababababababababababababababababababababababababababababababababababababababab",
         "qr": "https://catalogo-vpfe.dian.gov.co/document/searchqr?documentkey=abababababababababababababababababababababababababababababababababababababababababababababababab",
         "issued_at": "2026-10-23T09:15:02-05:00",
         "submission": "sync",
         "period": {
          "hire_date": "2024-03-01",
          "start": "2026-09-01",
          "end": "2026-09-30"
         },
         "pay_period": "5",
         "currency": "COP",
         "notes": [
          "Nómina de septiembre de 2026"
         ],
         "employee": {
          "type": "01",
          "subtype": "00",
          "high_risk_pension": false,
          "document_type": "13",
          "document_number": "1000000101",
          "first_surname": "PRUEBA",
          "second_surname": "NOMINA01",
          "first_name": "TRABAJADOR",
          "other_names": "DE PRUEBA",
          "workplace": {
           "country": "CO",
           "municipality_code": "76001",
           "address": "Calle 1 # 1-1"
          },
          "integral_salary": false,
          "contract_type": "2",
          "salary": "1423500",
          "code": "TRAB-01"
         },
         "payment": {
          "form": "1",
          "method": "42",
          "bank": "Banco de Pruebas",
          "account_type": "Ahorros",
          "account_number": "0001234501"
         },
         "payment_dates": [
          "2026-09-30"
         ],
         "earnings": {
          "basic": {
           "days": 30,
           "amount": "1423500"
          },
          "transport": [
           {
            "allowance": "200000"
           }
          ]
         },
         "deductions": {
          "health": {
           "percent": "4",
           "amount": "56940"
          },
          "pension": {
           "percent": "4",
           "amount": "56940"
          }
         },
         "totals": {
          "earnings": "1623500.00",
          "deductions": "113880.00",
          "net": "1509620.00"
         },
         "dian": {
          "status_code": "00",
          "message": "Procesado Correctamente.",
          "rules": []
         },
         "files": {
          "xml": true,
          "zip": true,
          "dian_response": true
         },
         "created_at": "2026-10-23T09:15:02-05:00",
         "updated_at": "2026-10-23T09:15:03-05:00"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "202": {
      "description": "Versión 2026-10-22: la DIAN no contestó (`status: processing`; Trevol termina el documento y avisa por webhook; no crees otro documento para la misma venta, y si repites con la misma Idempotency-Key respondemos sin enviar) o el documento se está enviando (`status: sending`); también la contingencia (`status: contingency`). Lleva `Location` y, salvo la contingencia, `Retry-After: 30`. En 2026-10-21 la DIAN sin contestar es un 503 `dian_unavailable`. También `status: validating` (en las dos versiones): el set de pruebas de habilitación de nómina recibió el documento y todavía lo valida; reintentar con la misma Idempotency-Key, `POST …/send` o corregir responde lo mismo SIN reenviar (`PUT` en ese estado es 409 `invalid_state`).",
      "headers": {
       "Location": {
        "schema": {
         "type": "string"
        }
       },
       "Retry-After": {
        "schema": {
         "type": "integer"
        }
       },
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Payroll"
        }
       }
      }
     },
     "402": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "409": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        },
        "examples": {
         "duplicado": {
          "summary": "Ya hay un 102 de ese trabajador y mes (producción, o habilitación con el set aceptado)",
          "value": {
           "type": "https://platform.trevol.si/docs/errores#duplicate_document",
           "title": "Ya existe un documento igual",
           "status": 409,
           "code": "duplicate_document",
           "detail": "Ya hay una nómina electrónica de ese trabajador para ese mes: ajústala con POST /v1/payroll_adjustments.",
           "retryable": false,
           "existing_id": "pr_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
           "request_id": "req_5b1c5b1c5b1c5b1c5b1c5b1c"
          }
         }
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "422": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        },
        "examples": {
         "no_habilitada": {
          "summary": "La nómina de la empresa no está habilitada",
          "value": {
           "type": "https://platform.trevol.si/docs/errores#company_not_enabled",
           "title": "La empresa no está habilitada para facturar",
           "status": 422,
           "code": "company_not_enabled",
           "detail": "La empresa todavía no terminó la habilitación de la nómina electrónica ante la DIAN.",
           "retryable": false,
           "reason": "payroll_not_enabled",
           "request_id": "req_5b1c5b1c5b1c5b1c5b1c5b1c"
          }
         }
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "429": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "503": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     }
    },
    "description": "Emite el documento soporte de pago de **nómina electrónica** (102) de un trabajador para un periodo. Trevol valida todo el contrato (periodo, trabajador, devengados y deducciones) ANTES de reservar, calcula los totales, numera (prefijo de nómina de la empresa), firma y lo manda a la DIAN. **En producción hay un solo 102 por trabajador y por mes** (art. 1.5.3.2.2): otro es `409 duplicate_document` con `existing_id`; para cambiarlo usa `POST /v1/payroll_adjustments`. La empresa debe tener la nómina habilitada ante la DIAN (`company_not_enabled`, `payroll_not_enabled`): con una llave `live`, `habilitada`; con una `test`, también el set de pruebas (`GET /v1/company` → `capabilities.payroll`). En el set de pruebas de habilitación responde `202 validating` en las dos versiones y reintentar no lo reenvía. No hay PDF ni correo: `xml`, `zip` y `dian_response`. Se cobra por empleado. Los datos del trabajador solo salen al dueño de la llave: no van en los webhooks ni en el registro de peticiones, y la respuesta guardada para la idempotencia no los copia.\n\n**Respuestas.** `201` la DIAN lo validó (`status: accepted`). `202` solo en la versión 2026-10-22: la DIAN no contestó (`processing`), otra petición lo está enviando (`sending`) o, en habilitación, el set de pruebas todavía lo valida (`validating`, en las dos versiones); trae `Location` y `Retry-After`, y el resultado llega por GET y por webhook: **no crees otro documento para la misma operación**. `422` `validation_error` (se revisó a fondo ANTES de reservar: no se gastó el número, y `errors[]` dice el campo), `dian_rejected` (con `document` y las reglas traducidas; corrige con `PUT` y el mismo número), `company_not_enabled` o `numbering_unavailable` (con `reason`). `402` `insufficient_balance` (producción sin saldo: queda `pending` con su número). `409` `external_id_in_use` o `duplicate_document` (con `existing_id`). `503` `dian_unavailable` en la 2026-10-21. Pide `Idempotency-Key`: repetir la misma devuelve lo mismo sin enviar nada.",
    "tags": [
     "Nómina electrónica"
    ],
    "operationId": "createPayroll"
   },
   "get": {
    "summary": "Listar (nómina electrónica)",
    "parameters": [
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 100
      }
     },
     {
      "name": "starting_after",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "status",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "external_id",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "created_from",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "created_to",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "employee_code",
      "in": "query",
      "schema": {
       "type": "string",
       "maxLength": 50,
       "description": "Solo en nóminas: el código interno del empleado (`employee.code`). No hay filtro por el documento del trabajador: la cédula en la URL quedaría en los registros."
      }
     },
     {
      "name": "period_end_from",
      "in": "query",
      "schema": {
       "type": "string",
       "format": "date",
       "description": "Solo en nóminas: el fin del periodo liquidado, desde (AAAA-MM-DD)."
      }
     },
     {
      "name": "period_end_to",
      "in": "query",
      "schema": {
       "type": "string",
       "format": "date",
       "description": "Solo en nóminas: el fin del periodo liquidado, hasta (AAAA-MM-DD)."
      }
     }
    ],
    "responses": {
     "200": {
      "description": "{object: list, data, has_more, next_cursor}",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "object",
          "data",
          "has_more",
          "next_cursor"
         ],
         "properties": {
          "object": {
           "type": "string",
           "enum": [
            "list"
           ]
          },
          "data": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Payroll"
           }
          },
          "has_more": {
           "type": "boolean"
          },
          "next_cursor": {
           "type": [
            "string",
            "null"
           ]
          }
         }
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "Paginación por cursor y filtros `status`, `external_id`, `created_from`, `created_to`, `employee_code` (el código interno del empleado) y `period_end_from` / `period_end_to`. **No se filtra por el documento del trabajador**: la cédula en la URL quedaría en los registros del servidor.",
    "tags": [
     "Nómina electrónica"
    ],
    "operationId": "listPayrolls"
   }
  },
  "/payrolls/preview": {
   "post": {
    "summary": "Calcular una nómina electrónica sin emitirla",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/PayrollInput"
       },
       "examples": {
        "mensual": {
         "summary": "Nómina de un mes completo",
         "value": {
          "external_id": "NOM-2026-09-001",
          "period": {
           "hire_date": "2024-03-01",
           "start": "2026-09-01",
           "end": "2026-09-30"
          },
          "pay_period": "5",
          "notes": [
           "Nómina de septiembre de 2026"
          ],
          "employee": {
           "type": "01",
           "subtype": "00",
           "high_risk_pension": false,
           "document_type": "13",
           "document_number": "1000000101",
           "first_surname": "PRUEBA",
           "second_surname": "NOMINA01",
           "first_name": "TRABAJADOR",
           "other_names": "DE PRUEBA",
           "workplace": {
            "country": "CO",
            "municipality_code": "76001",
            "address": "Calle 1 # 1-1"
           },
           "integral_salary": false,
           "contract_type": "2",
           "salary": "1423500",
           "code": "TRAB-01"
          },
          "payment": {
           "form": "1",
           "method": "42",
           "bank": "Banco de Pruebas",
           "account_type": "Ahorros",
           "account_number": "0001234501"
          },
          "payment_dates": [
           "2026-09-30"
          ],
          "earnings": {
           "basic": {
            "days": 30,
            "amount": "1423500"
           },
           "transport": [
            {
             "allowance": "200000"
            }
           ]
          },
          "deductions": {
           "health": {
            "percent": "4",
            "amount": "56940"
           },
           "pension": {
            "percent": "4",
            "amount": "56940"
           }
          }
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Totales",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Preview"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "Valida y calcula los totales de la nómina **sin** reservar un número ni enviar nada. No pide `Idempotency-Key` y no se cobra. El trabajador que mandaste vuelve en la respuesta; Trevol no lo guarda.",
    "tags": [
     "Nómina electrónica"
    ],
    "operationId": "previewPayroll"
   }
  },
  "/payrolls/{id}": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Una nómina electrónica",
    "responses": {
     "200": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Payroll"
        },
        "example": {
         "id": "pr_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
         "object": "payroll",
         "environment": "live",
         "status": "accepted",
         "number": "NE15",
         "prefix": "NE",
         "external_id": "NOM-2026-09-001",
         "origin": "api",
         "cune": "abababababababababababababababababababababababababababababababababababababababababababababababab",
         "qr": "https://catalogo-vpfe.dian.gov.co/document/searchqr?documentkey=abababababababababababababababababababababababababababababababababababababababababababababababab",
         "issued_at": "2026-10-23T09:15:02-05:00",
         "submission": "sync",
         "period": {
          "hire_date": "2024-03-01",
          "start": "2026-09-01",
          "end": "2026-09-30"
         },
         "pay_period": "5",
         "currency": "COP",
         "notes": [
          "Nómina de septiembre de 2026"
         ],
         "employee": {
          "type": "01",
          "subtype": "00",
          "high_risk_pension": false,
          "document_type": "13",
          "document_number": "1000000101",
          "first_surname": "PRUEBA",
          "second_surname": "NOMINA01",
          "first_name": "TRABAJADOR",
          "other_names": "DE PRUEBA",
          "workplace": {
           "country": "CO",
           "municipality_code": "76001",
           "address": "Calle 1 # 1-1"
          },
          "integral_salary": false,
          "contract_type": "2",
          "salary": "1423500",
          "code": "TRAB-01"
         },
         "payment": {
          "form": "1",
          "method": "42",
          "bank": "Banco de Pruebas",
          "account_type": "Ahorros",
          "account_number": "0001234501"
         },
         "payment_dates": [
          "2026-09-30"
         ],
         "earnings": {
          "basic": {
           "days": 30,
           "amount": "1423500"
          },
          "transport": [
           {
            "allowance": "200000"
           }
          ]
         },
         "deductions": {
          "health": {
           "percent": "4",
           "amount": "56940"
          },
          "pension": {
           "percent": "4",
           "amount": "56940"
          }
         },
         "totals": {
          "earnings": "1623500.00",
          "deductions": "113880.00",
          "net": "1509620.00"
         },
         "dian": {
          "status_code": "00",
          "message": "Procesado Correctamente.",
          "rules": []
         },
         "files": {
          "xml": true,
          "zip": true,
          "dian_response": true
         },
         "created_at": "2026-10-23T09:15:02-05:00",
         "updated_at": "2026-10-23T09:15:03-05:00"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "La nómina tal como se emitió, con el trabajador, los devengados, las deducciones y los totales (`earnings`, `deductions`, `net`).",
    "tags": [
     "Nómina electrónica"
    ],
    "operationId": "retrievePayroll"
   },
   "put": {
    "summary": "Corregir una nómina electrónica rechazada (mismo número) y reenviarla",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "required": true,
      "description": "Obligatoria: 1 a 255 caracteres ASCII visibles, única por pedido (7 días).",
      "schema": {
       "type": "string",
       "maxLength": 255
      }
     },
     {
      "name": "Trevol-Version",
      "in": "header",
      "required": false,
      "description": "La versión de la API. Si no viene, la de la llave (las llaves de antes quedan en 2026-10-21; las nuevas nacen en 2026-10-22).",
      "schema": {
       "type": "string",
       "enum": [
        "2026-10-21",
        "2026-10-22"
       ]
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/PayrollInput"
       },
       "examples": {
        "mensual": {
         "summary": "Nómina de un mes completo",
         "value": {
          "external_id": "NOM-2026-09-001",
          "period": {
           "hire_date": "2024-03-01",
           "start": "2026-09-01",
           "end": "2026-09-30"
          },
          "pay_period": "5",
          "notes": [
           "Nómina de septiembre de 2026"
          ],
          "employee": {
           "type": "01",
           "subtype": "00",
           "high_risk_pension": false,
           "document_type": "13",
           "document_number": "1000000101",
           "first_surname": "PRUEBA",
           "second_surname": "NOMINA01",
           "first_name": "TRABAJADOR",
           "other_names": "DE PRUEBA",
           "workplace": {
            "country": "CO",
            "municipality_code": "76001",
            "address": "Calle 1 # 1-1"
           },
           "integral_salary": false,
           "contract_type": "2",
           "salary": "1423500",
           "code": "TRAB-01"
          },
          "payment": {
           "form": "1",
           "method": "42",
           "bank": "Banco de Pruebas",
           "account_type": "Ahorros",
           "account_number": "0001234501"
          },
          "payment_dates": [
           "2026-09-30"
          ],
          "earnings": {
           "basic": {
            "days": 30,
            "amount": "1423500"
           },
           "transport": [
            {
             "allowance": "200000"
            }
           ]
          },
          "deductions": {
           "health": {
            "percent": "4",
            "amount": "56940"
           },
           "pension": {
            "percent": "4",
            "amount": "56940"
           }
          }
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Payroll"
        },
        "example": {
         "id": "pr_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
         "object": "payroll",
         "environment": "live",
         "status": "accepted",
         "number": "NE15",
         "prefix": "NE",
         "external_id": "NOM-2026-09-001",
         "origin": "api",
         "cune": "abababababababababababababababababababababababababababababababababababababababababababababababab",
         "qr": "https://catalogo-vpfe.dian.gov.co/document/searchqr?documentkey=abababababababababababababababababababababababababababababababababababababababababababababababab",
         "issued_at": "2026-10-23T09:15:02-05:00",
         "submission": "sync",
         "period": {
          "hire_date": "2024-03-01",
          "start": "2026-09-01",
          "end": "2026-09-30"
         },
         "pay_period": "5",
         "currency": "COP",
         "notes": [
          "Nómina de septiembre de 2026"
         ],
         "employee": {
          "type": "01",
          "subtype": "00",
          "high_risk_pension": false,
          "document_type": "13",
          "document_number": "1000000101",
          "first_surname": "PRUEBA",
          "second_surname": "NOMINA01",
          "first_name": "TRABAJADOR",
          "other_names": "DE PRUEBA",
          "workplace": {
           "country": "CO",
           "municipality_code": "76001",
           "address": "Calle 1 # 1-1"
          },
          "integral_salary": false,
          "contract_type": "2",
          "salary": "1423500",
          "code": "TRAB-01"
         },
         "payment": {
          "form": "1",
          "method": "42",
          "bank": "Banco de Pruebas",
          "account_type": "Ahorros",
          "account_number": "0001234501"
         },
         "payment_dates": [
          "2026-09-30"
         ],
         "earnings": {
          "basic": {
           "days": 30,
           "amount": "1423500"
          },
          "transport": [
           {
            "allowance": "200000"
           }
          ]
         },
         "deductions": {
          "health": {
           "percent": "4",
           "amount": "56940"
          },
          "pension": {
           "percent": "4",
           "amount": "56940"
          }
         },
         "totals": {
          "earnings": "1623500.00",
          "deductions": "113880.00",
          "net": "1509620.00"
         },
         "dian": {
          "status_code": "00",
          "message": "Procesado Correctamente.",
          "rules": []
         },
         "files": {
          "xml": true,
          "zip": true,
          "dian_response": true
         },
         "created_at": "2026-10-23T09:15:02-05:00",
         "updated_at": "2026-10-23T09:15:03-05:00"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "202": {
      "description": "Versión 2026-10-22: la DIAN no contestó (`status: processing`; Trevol termina el documento y avisa por webhook; no crees otro documento para la misma venta, y si repites con la misma Idempotency-Key respondemos sin enviar) o el documento se está enviando (`status: sending`); también la contingencia (`status: contingency`). Lleva `Location` y, salvo la contingencia, `Retry-After: 30`. En 2026-10-21 la DIAN sin contestar es un 503 `dian_unavailable`. También `status: validating` (en las dos versiones): el set de pruebas de habilitación de nómina recibió el documento y todavía lo valida; reintentar con la misma Idempotency-Key, `POST …/send` o corregir responde lo mismo SIN reenviar (`PUT` en ese estado es 409 `invalid_state`).",
      "headers": {
       "Location": {
        "schema": {
         "type": "string"
        }
       },
       "Retry-After": {
        "schema": {
         "type": "integer"
        }
       },
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Payroll"
        }
       }
      }
     },
     "409": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     }
    },
    "description": "Corrige una nómina rechazada con el **mismo número** y la vuelve a enviar. `409 invalid_state` si el set de pruebas la está validando.\n\nSolo si el documento está `rejected`, `error` o `pending`. Uno `accepted` no se corrige (se ajusta con una nota) y uno que la DIAN todavía verifica es `409 invalid_state`: espera el resultado. El `external_id` y la numeración no se cambian. Pide `Idempotency-Key`.",
    "tags": [
     "Nómina electrónica"
    ],
    "operationId": "correctPayroll"
   }
  },
  "/payrolls/{id}/send": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "post": {
    "summary": "Reenviar una pendiente o en error",
    "parameters": [
     {
      "name": "Trevol-Version",
      "in": "header",
      "required": false,
      "description": "La versión de la API. Si no viene, la de la llave (las llaves de antes quedan en 2026-10-21; las nuevas nacen en 2026-10-22).",
      "schema": {
       "type": "string",
       "enum": [
        "2026-10-21",
        "2026-10-22"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Payroll"
        },
        "example": {
         "id": "pr_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
         "object": "payroll",
         "environment": "live",
         "status": "accepted",
         "number": "NE15",
         "prefix": "NE",
         "external_id": "NOM-2026-09-001",
         "origin": "api",
         "cune": "abababababababababababababababababababababababababababababababababababababababababababababababab",
         "qr": "https://catalogo-vpfe.dian.gov.co/document/searchqr?documentkey=abababababababababababababababababababababababababababababababababababababababababababababababab",
         "issued_at": "2026-10-23T09:15:02-05:00",
         "submission": "sync",
         "period": {
          "hire_date": "2024-03-01",
          "start": "2026-09-01",
          "end": "2026-09-30"
         },
         "pay_period": "5",
         "currency": "COP",
         "notes": [
          "Nómina de septiembre de 2026"
         ],
         "employee": {
          "type": "01",
          "subtype": "00",
          "high_risk_pension": false,
          "document_type": "13",
          "document_number": "1000000101",
          "first_surname": "PRUEBA",
          "second_surname": "NOMINA01",
          "first_name": "TRABAJADOR",
          "other_names": "DE PRUEBA",
          "workplace": {
           "country": "CO",
           "municipality_code": "76001",
           "address": "Calle 1 # 1-1"
          },
          "integral_salary": false,
          "contract_type": "2",
          "salary": "1423500",
          "code": "TRAB-01"
         },
         "payment": {
          "form": "1",
          "method": "42",
          "bank": "Banco de Pruebas",
          "account_type": "Ahorros",
          "account_number": "0001234501"
         },
         "payment_dates": [
          "2026-09-30"
         ],
         "earnings": {
          "basic": {
           "days": 30,
           "amount": "1423500"
          },
          "transport": [
           {
            "allowance": "200000"
           }
          ]
         },
         "deductions": {
          "health": {
           "percent": "4",
           "amount": "56940"
          },
          "pension": {
           "percent": "4",
           "amount": "56940"
          }
         },
         "totals": {
          "earnings": "1623500.00",
          "deductions": "113880.00",
          "net": "1509620.00"
         },
         "dian": {
          "status_code": "00",
          "message": "Procesado Correctamente.",
          "rules": []
         },
         "files": {
          "xml": true,
          "zip": true,
          "dian_response": true
         },
         "created_at": "2026-10-23T09:15:02-05:00",
         "updated_at": "2026-10-23T09:15:03-05:00"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "202": {
      "description": "Versión 2026-10-22: la DIAN no contestó (`status: processing`; Trevol termina el documento y avisa por webhook; no crees otro documento para la misma venta, y si repites con la misma Idempotency-Key respondemos sin enviar) o el documento se está enviando (`status: sending`); también la contingencia (`status: contingency`). Lleva `Location` y, salvo la contingencia, `Retry-After: 30`. En 2026-10-21 la DIAN sin contestar es un 503 `dian_unavailable`. También `status: validating` (en las dos versiones): el set de pruebas de habilitación de nómina recibió el documento y todavía lo valida; reintentar con la misma Idempotency-Key, `POST …/send` o corregir responde lo mismo SIN reenviar (`PUT` en ese estado es 409 `invalid_state`).",
      "headers": {
       "Location": {
        "schema": {
         "type": "string"
        }
       },
       "Retry-After": {
        "schema": {
         "type": "integer"
        }
       },
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Payroll"
        }
       }
      }
     },
     "409": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "Vuelve a enviar una nómina `pending` o `error`. Si el set de pruebas la valida (`validating`), solo consulta.\n\nSin cuerpo. Con un documento `accepted` responde `200` con el documento tal cual; con uno que la DIAN todavía verifica no reenvía nada (`202`); con uno `rejected` es `409 invalid_state` (se corrige con `PUT`). No pide `Idempotency-Key` (reintentarlo es seguro).",
    "tags": [
     "Nómina electrónica"
    ],
    "operationId": "sendPayroll"
   }
  },
  "/payrolls/{id}/xml": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Archivo xml",
    "responses": {
     "200": {
      "description": "xml",
      "content": {
       "application/xml": {
        "schema": {
         "type": "string",
         "format": "binary"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "El XML firmado que se mandó a la DIAN (`application/xml`).",
    "tags": [
     "Nómina electrónica"
    ],
    "operationId": "downloadPayrollXml"
   }
  },
  "/payrolls/{id}/zip": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Archivo zip",
    "responses": {
     "200": {
      "description": "zip",
      "content": {
       "application/zip": {
        "schema": {
         "type": "string",
         "format": "binary"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "El ZIP del documento (`application/zip`).",
    "tags": [
     "Nómina electrónica"
    ],
    "operationId": "downloadPayrollZip"
   }
  },
  "/payrolls/{id}/dian_response": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Archivo dian_response",
    "responses": {
     "200": {
      "description": "dian_response",
      "content": {
       "application/xml": {
        "schema": {
         "type": "string",
         "format": "binary"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "El `ApplicationResponse` con que la DIAN contestó (`application/xml`), si la DIAN lo devolvió.",
    "tags": [
     "Nómina electrónica"
    ],
    "operationId": "downloadPayrollDianResponse"
   }
  },
  "/payroll_adjustments": {
   "post": {
    "summary": "Emitir una nota de ajuste de nómina",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "required": true,
      "description": "Obligatoria: 1 a 255 caracteres ASCII visibles, única por pedido (7 días).",
      "schema": {
       "type": "string",
       "maxLength": 255
      }
     },
     {
      "name": "Trevol-Version",
      "in": "header",
      "required": false,
      "description": "La versión de la API. Si no viene, la de la llave (las llaves de antes quedan en 2026-10-21; las nuevas nacen en 2026-10-22).",
      "schema": {
       "type": "string",
       "enum": [
        "2026-10-21",
        "2026-10-22"
       ]
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/PayrollAdjustmentInput"
       },
       "examples": {
        "reemplazar": {
         "summary": "Reemplazar: la nómina corregida",
         "value": {
          "external_id": "NOM-2026-09-001-R",
          "period": {
           "hire_date": "2024-03-01",
           "start": "2026-09-01",
           "end": "2026-09-30"
          },
          "pay_period": "5",
          "notes": [
           "Nómina de septiembre de 2026"
          ],
          "employee": {
           "type": "01",
           "subtype": "00",
           "high_risk_pension": false,
           "document_type": "13",
           "document_number": "1000000101",
           "first_surname": "PRUEBA",
           "second_surname": "NOMINA01",
           "first_name": "TRABAJADOR",
           "other_names": "DE PRUEBA",
           "workplace": {
            "country": "CO",
            "municipality_code": "76001",
            "address": "Calle 1 # 1-1"
           },
           "integral_salary": false,
           "contract_type": "2",
           "salary": "1423500",
           "code": "TRAB-01"
          },
          "payment": {
           "form": "1",
           "method": "42",
           "bank": "Banco de Pruebas",
           "account_type": "Ahorros",
           "account_number": "0001234501"
          },
          "payment_dates": [
           "2026-09-30"
          ],
          "earnings": {
           "basic": {
            "days": 30,
            "amount": "1423500"
           },
           "transport": [
            {
             "allowance": "210000"
            }
           ]
          },
          "deductions": {
           "health": {
            "percent": "4",
            "amount": "56940"
           },
           "pension": {
            "percent": "4",
            "amount": "56940"
           }
          },
          "type": "replace",
          "predecessor": {
           "id": "pr_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
          }
         }
        },
        "eliminar": {
         "summary": "Eliminar: la nómina no debió enviarse",
         "value": {
          "external_id": "NOM-2026-09-001-E",
          "type": "delete",
          "predecessor": {
           "id": "pr_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
          },
          "notes": [
           "Enviada por error"
          ]
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PayrollAdjustment"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "202": {
      "description": "Versión 2026-10-22: la DIAN no contestó (`status: processing`; Trevol termina el documento y avisa por webhook; no crees otro documento para la misma venta, y si repites con la misma Idempotency-Key respondemos sin enviar) o el documento se está enviando (`status: sending`); también la contingencia (`status: contingency`). Lleva `Location` y, salvo la contingencia, `Retry-After: 30`. En 2026-10-21 la DIAN sin contestar es un 503 `dian_unavailable`. También `status: validating` (en las dos versiones): el set de pruebas de habilitación de nómina recibió el documento y todavía lo valida; reintentar con la misma Idempotency-Key, `POST …/send` o corregir responde lo mismo SIN reenviar (`PUT` en ese estado es 409 `invalid_state`).",
      "headers": {
       "Location": {
        "schema": {
         "type": "string"
        }
       },
       "Retry-After": {
        "schema": {
         "type": "integer"
        }
       },
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PayrollAdjustment"
        }
       }
      }
     },
     "402": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "409": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "422": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "429": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "503": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     }
    },
    "description": "Emite la **nota de ajuste de nómina electrónica** (103). `type: \"replace\"` (Reemplazar) lleva la nómina completa corregida; `type: \"delete\"` (Eliminar) solo el predecesor y las notas. El `predecessor` es una nómina de Trevol (`pr_…` o `pra_…`, validada) o una de otra plataforma (`number`, `cune`, `issue_date`); es de la misma empresa y ambiente de la llave, del mismo trabajador, y el último de su cadena. Una nómina eliminada no se ajusta.\n\n**Respuestas.** `201` la DIAN lo validó (`status: accepted`). `202` solo en la versión 2026-10-22: la DIAN no contestó (`processing`), otra petición lo está enviando (`sending`) o, en habilitación, el set de pruebas todavía lo valida (`validating`, en las dos versiones); trae `Location` y `Retry-After`, y el resultado llega por GET y por webhook: **no crees otro documento para la misma operación**. `422` `validation_error` (se revisó a fondo ANTES de reservar: no se gastó el número, y `errors[]` dice el campo), `dian_rejected` (con `document` y las reglas traducidas; corrige con `PUT` y el mismo número), `company_not_enabled` o `numbering_unavailable` (con `reason`). `402` `insufficient_balance` (producción sin saldo: queda `pending` con su número). `409` `external_id_in_use` o `duplicate_document` (con `existing_id`). `503` `dian_unavailable` en la 2026-10-21. Pide `Idempotency-Key`: repetir la misma devuelve lo mismo sin enviar nada.",
    "tags": [
     "Nómina electrónica"
    ],
    "operationId": "createPayrollAdjustment"
   },
   "get": {
    "summary": "Listar (nota de ajuste de nómina)",
    "parameters": [
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 100
      }
     },
     {
      "name": "starting_after",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "status",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "external_id",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "created_from",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "created_to",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "employee_code",
      "in": "query",
      "schema": {
       "type": "string",
       "maxLength": 50,
       "description": "Solo en nóminas: el código interno del empleado (`employee.code`). No hay filtro por el documento del trabajador: la cédula en la URL quedaría en los registros."
      }
     },
     {
      "name": "period_end_from",
      "in": "query",
      "schema": {
       "type": "string",
       "format": "date",
       "description": "Solo en nóminas: el fin del periodo liquidado, desde (AAAA-MM-DD)."
      }
     },
     {
      "name": "period_end_to",
      "in": "query",
      "schema": {
       "type": "string",
       "format": "date",
       "description": "Solo en nóminas: el fin del periodo liquidado, hasta (AAAA-MM-DD)."
      }
     }
    ],
    "responses": {
     "200": {
      "description": "{object: list, data, has_more, next_cursor}",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "object",
          "data",
          "has_more",
          "next_cursor"
         ],
         "properties": {
          "object": {
           "type": "string",
           "enum": [
            "list"
           ]
          },
          "data": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/PayrollAdjustment"
           }
          },
          "has_more": {
           "type": "boolean"
          },
          "next_cursor": {
           "type": [
            "string",
            "null"
           ]
          }
         }
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "Paginación por cursor y los mismos filtros de `GET /v1/payrolls` (sin documento del trabajador).",
    "tags": [
     "Nómina electrónica"
    ],
    "operationId": "listPayrollAdjustments"
   }
  },
  "/payroll_adjustments/preview": {
   "post": {
    "summary": "Calcular una nota de ajuste de nómina sin emitirla",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/PayrollAdjustmentInput"
       },
       "examples": {
        "reemplazar": {
         "summary": "Reemplazar: la nómina corregida",
         "value": {
          "external_id": "NOM-2026-09-001-R",
          "period": {
           "hire_date": "2024-03-01",
           "start": "2026-09-01",
           "end": "2026-09-30"
          },
          "pay_period": "5",
          "notes": [
           "Nómina de septiembre de 2026"
          ],
          "employee": {
           "type": "01",
           "subtype": "00",
           "high_risk_pension": false,
           "document_type": "13",
           "document_number": "1000000101",
           "first_surname": "PRUEBA",
           "second_surname": "NOMINA01",
           "first_name": "TRABAJADOR",
           "other_names": "DE PRUEBA",
           "workplace": {
            "country": "CO",
            "municipality_code": "76001",
            "address": "Calle 1 # 1-1"
           },
           "integral_salary": false,
           "contract_type": "2",
           "salary": "1423500",
           "code": "TRAB-01"
          },
          "payment": {
           "form": "1",
           "method": "42",
           "bank": "Banco de Pruebas",
           "account_type": "Ahorros",
           "account_number": "0001234501"
          },
          "payment_dates": [
           "2026-09-30"
          ],
          "earnings": {
           "basic": {
            "days": 30,
            "amount": "1423500"
           },
           "transport": [
            {
             "allowance": "210000"
            }
           ]
          },
          "deductions": {
           "health": {
            "percent": "4",
            "amount": "56940"
           },
           "pension": {
            "percent": "4",
            "amount": "56940"
           }
          },
          "type": "replace",
          "predecessor": {
           "id": "pr_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
          }
         }
        },
        "eliminar": {
         "summary": "Eliminar: la nómina no debió enviarse",
         "value": {
          "external_id": "NOM-2026-09-001-E",
          "type": "delete",
          "predecessor": {
           "id": "pr_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
          },
          "notes": [
           "Enviada por error"
          ]
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Totales",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Preview"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "Valida y calcula la nota de ajuste **sin** reservar un número ni enviar nada.",
    "tags": [
     "Nómina electrónica"
    ],
    "operationId": "previewPayrollAdjustment"
   }
  },
  "/payroll_adjustments/{id}": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Una nota de ajuste de nómina",
    "responses": {
     "200": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PayrollAdjustment"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "La nota de ajuste, con `type` y `predecessor` (con el prefijo de la clase de su predecesor). El Eliminar no trae trabajador, devengados ni deducciones.",
    "tags": [
     "Nómina electrónica"
    ],
    "operationId": "retrievePayrollAdjustment"
   },
   "put": {
    "summary": "Corregir una nota de ajuste de nómina rechazada (mismo número) y reenviarla",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "required": true,
      "description": "Obligatoria: 1 a 255 caracteres ASCII visibles, única por pedido (7 días).",
      "schema": {
       "type": "string",
       "maxLength": 255
      }
     },
     {
      "name": "Trevol-Version",
      "in": "header",
      "required": false,
      "description": "La versión de la API. Si no viene, la de la llave (las llaves de antes quedan en 2026-10-21; las nuevas nacen en 2026-10-22).",
      "schema": {
       "type": "string",
       "enum": [
        "2026-10-21",
        "2026-10-22"
       ]
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/PayrollAdjustmentInput"
       },
       "examples": {
        "reemplazar": {
         "summary": "Reemplazar: la nómina corregida",
         "value": {
          "external_id": "NOM-2026-09-001-R",
          "period": {
           "hire_date": "2024-03-01",
           "start": "2026-09-01",
           "end": "2026-09-30"
          },
          "pay_period": "5",
          "notes": [
           "Nómina de septiembre de 2026"
          ],
          "employee": {
           "type": "01",
           "subtype": "00",
           "high_risk_pension": false,
           "document_type": "13",
           "document_number": "1000000101",
           "first_surname": "PRUEBA",
           "second_surname": "NOMINA01",
           "first_name": "TRABAJADOR",
           "other_names": "DE PRUEBA",
           "workplace": {
            "country": "CO",
            "municipality_code": "76001",
            "address": "Calle 1 # 1-1"
           },
           "integral_salary": false,
           "contract_type": "2",
           "salary": "1423500",
           "code": "TRAB-01"
          },
          "payment": {
           "form": "1",
           "method": "42",
           "bank": "Banco de Pruebas",
           "account_type": "Ahorros",
           "account_number": "0001234501"
          },
          "payment_dates": [
           "2026-09-30"
          ],
          "earnings": {
           "basic": {
            "days": 30,
            "amount": "1423500"
           },
           "transport": [
            {
             "allowance": "210000"
            }
           ]
          },
          "deductions": {
           "health": {
            "percent": "4",
            "amount": "56940"
           },
           "pension": {
            "percent": "4",
            "amount": "56940"
           }
          },
          "type": "replace",
          "predecessor": {
           "id": "pr_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
          }
         }
        },
        "eliminar": {
         "summary": "Eliminar: la nómina no debió enviarse",
         "value": {
          "external_id": "NOM-2026-09-001-E",
          "type": "delete",
          "predecessor": {
           "id": "pr_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
          },
          "notes": [
           "Enviada por error"
          ]
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PayrollAdjustment"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "202": {
      "description": "Versión 2026-10-22: la DIAN no contestó (`status: processing`; Trevol termina el documento y avisa por webhook; no crees otro documento para la misma venta, y si repites con la misma Idempotency-Key respondemos sin enviar) o el documento se está enviando (`status: sending`); también la contingencia (`status: contingency`). Lleva `Location` y, salvo la contingencia, `Retry-After: 30`. En 2026-10-21 la DIAN sin contestar es un 503 `dian_unavailable`. También `status: validating` (en las dos versiones): el set de pruebas de habilitación de nómina recibió el documento y todavía lo valida; reintentar con la misma Idempotency-Key, `POST …/send` o corregir responde lo mismo SIN reenviar (`PUT` en ese estado es 409 `invalid_state`).",
      "headers": {
       "Location": {
        "schema": {
         "type": "string"
        }
       },
       "Retry-After": {
        "schema": {
         "type": "integer"
        }
       },
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PayrollAdjustment"
        }
       }
      }
     },
     "409": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     }
    },
    "description": "Corrige una nota de ajuste rechazada con el **mismo número** y la vuelve a enviar.\n\nSolo si el documento está `rejected`, `error` o `pending`. Uno `accepted` no se corrige (se ajusta con una nota) y uno que la DIAN todavía verifica es `409 invalid_state`: espera el resultado. El `external_id` y la numeración no se cambian. Pide `Idempotency-Key`.",
    "tags": [
     "Nómina electrónica"
    ],
    "operationId": "correctPayrollAdjustment"
   }
  },
  "/payroll_adjustments/{id}/send": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "post": {
    "summary": "Reenviar una pendiente o en error",
    "parameters": [
     {
      "name": "Trevol-Version",
      "in": "header",
      "required": false,
      "description": "La versión de la API. Si no viene, la de la llave (las llaves de antes quedan en 2026-10-21; las nuevas nacen en 2026-10-22).",
      "schema": {
       "type": "string",
       "enum": [
        "2026-10-21",
        "2026-10-22"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PayrollAdjustment"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "202": {
      "description": "Versión 2026-10-22: la DIAN no contestó (`status: processing`; Trevol termina el documento y avisa por webhook; no crees otro documento para la misma venta, y si repites con la misma Idempotency-Key respondemos sin enviar) o el documento se está enviando (`status: sending`); también la contingencia (`status: contingency`). Lleva `Location` y, salvo la contingencia, `Retry-After: 30`. En 2026-10-21 la DIAN sin contestar es un 503 `dian_unavailable`. También `status: validating` (en las dos versiones): el set de pruebas de habilitación de nómina recibió el documento y todavía lo valida; reintentar con la misma Idempotency-Key, `POST …/send` o corregir responde lo mismo SIN reenviar (`PUT` en ese estado es 409 `invalid_state`).",
      "headers": {
       "Location": {
        "schema": {
         "type": "string"
        }
       },
       "Retry-After": {
        "schema": {
         "type": "integer"
        }
       },
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PayrollAdjustment"
        }
       }
      }
     },
     "409": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "Vuelve a enviar una nota de ajuste `pending` o `error`.\n\nSin cuerpo. Con un documento `accepted` responde `200` con el documento tal cual; con uno que la DIAN todavía verifica no reenvía nada (`202`); con uno `rejected` es `409 invalid_state` (se corrige con `PUT`). No pide `Idempotency-Key` (reintentarlo es seguro).",
    "tags": [
     "Nómina electrónica"
    ],
    "operationId": "sendPayrollAdjustment"
   }
  },
  "/payroll_adjustments/{id}/xml": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Archivo xml",
    "responses": {
     "200": {
      "description": "xml",
      "content": {
       "application/xml": {
        "schema": {
         "type": "string",
         "format": "binary"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "El XML firmado que se mandó a la DIAN (`application/xml`).",
    "tags": [
     "Nómina electrónica"
    ],
    "operationId": "downloadPayrollAdjustmentXml"
   }
  },
  "/payroll_adjustments/{id}/zip": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Archivo zip",
    "responses": {
     "200": {
      "description": "zip",
      "content": {
       "application/zip": {
        "schema": {
         "type": "string",
         "format": "binary"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "El ZIP del documento (`application/zip`).",
    "tags": [
     "Nómina electrónica"
    ],
    "operationId": "downloadPayrollAdjustmentZip"
   }
  },
  "/payroll_adjustments/{id}/dian_response": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Archivo dian_response",
    "responses": {
     "200": {
      "description": "dian_response",
      "content": {
       "application/xml": {
        "schema": {
         "type": "string",
         "format": "binary"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "El `ApplicationResponse` con que la DIAN contestó (`application/xml`), si la DIAN lo devolvió.",
    "tags": [
     "Nómina electrónica"
    ],
    "operationId": "downloadPayrollAdjustmentDianResponse"
   }
  },
  "/radian_events": {
   "post": {
    "summary": "Emitir un evento RADIAN",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "required": true,
      "description": "Obligatoria: 1 a 255 caracteres ASCII visibles, única por pedido (7 días).",
      "schema": {
       "type": "string",
       "maxLength": 255
      }
     },
     {
      "name": "Trevol-Version",
      "in": "header",
      "required": false,
      "description": "La versión de la API. Si no viene, la de la llave (las llaves de antes quedan en 2026-10-21; las nuevas nacen en 2026-10-22).",
      "schema": {
       "type": "string",
       "enum": [
        "2026-10-21",
        "2026-10-22"
       ]
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/RadianEventInput"
       },
       "examples": {
        "acuse": {
         "summary": "Acuse de recibo (030) de una factura recibida",
         "value": {
          "external_id": "ERP-ACUSE-OJ1234",
          "event_code": "030",
          "invoice": {
           "cufe": "cdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd",
           "number": "OJ1234",
           "type": "01",
           "issuer": {
            "nit": "890330031",
            "check_digit": 3,
            "document_type": "31",
            "name": "OSPINA Y ASOCIADOS SAS"
           }
          }
         }
        },
        "reclamo": {
         "summary": "Reclamo (031) con su concepto",
         "value": {
          "external_id": "ERP-RECLAMO-OJ1234",
          "event_code": "031",
          "invoice": {
           "cufe": "cdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd",
           "number": "OJ1234",
           "type": "01",
           "issuer": {
            "nit": "890330031",
            "check_digit": 3,
            "document_type": "31",
            "name": "OSPINA Y ASOCIADOS SAS"
           }
          },
          "claim": {
           "code": "02",
           "note": "Faltaron dos cajas"
          }
         }
        },
        "tacita": {
         "summary": "Aceptación tácita (034) de una factura propia a crédito",
         "value": {
          "external_id": "ERP-TACITA-FE1234",
          "event_code": "034",
          "invoice_id": "inv_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
         }
        },
        "tacita_cufe": {
         "summary": "Aceptación tácita (034) de una factura propia emitida con otro software, por su CUFE",
         "value": {
          "external_id": "ERP-TACITA-FE4722",
          "event_code": "034",
          "invoice": {
           "cufe": "abababababababababababababababababababababababababababababababababababababababababababababababab",
           "number": "FE4722"
          }
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/RadianEvent"
        },
        "example": {
         "id": "rev_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
         "object": "radian_event",
         "environment": "test",
         "status": "accepted",
         "event_code": "030",
         "number": "AR994000123",
         "prefix": "AR",
         "external_id": "ERP-ACUSE-OJ1234",
         "origin": "api",
         "cude": "abababababababababababababababababababababababababababababababababababababababababababababababab",
         "issued_at": "2026-10-23T09:15:02-05:00",
         "invoice": {
          "cufe": "cdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd",
          "number": "OJ1234",
          "type": "01",
          "issuer": {
           "nit": "890330031",
           "check_digit": 3,
           "document_type": "31",
           "name": "OSPINA Y ASOCIADOS SAS"
          }
         },
         "claim": null,
         "software": "own",
         "provider": "company",
         "dian": {
          "status_code": "02",
          "message": "Documento validado por la DIAN",
          "rules": []
         },
         "already_registered": false,
         "already_registered_elsewhere": false,
         "tacit": false,
         "created_at": "2026-10-23T09:15:02-05:00",
         "updated_at": "2026-10-23T09:15:03-05:00"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "202": {
      "description": "Versión 2026-10-22: la DIAN no contestó (`status: processing`; Trevol termina el documento y avisa por webhook; no crees otro documento para la misma venta, y si repites con la misma Idempotency-Key respondemos sin enviar) o el documento se está enviando (`status: sending`); también la contingencia (`status: contingency`). Lleva `Location` y, salvo la contingencia, `Retry-After: 30`. En 2026-10-21 la DIAN sin contestar es un 503 `dian_unavailable`. También `status: validating` (en las dos versiones): la DIAN respondió 98; reintentar con la misma Idempotency-Key o `POST …/send` responde lo mismo SIN reenviar. En la 2026-10-21, el evento anterior que aún no aparece es 409 `previous_event_pending`.",
      "headers": {
       "Location": {
        "schema": {
         "type": "string"
        }
       },
       "Retry-After": {
        "schema": {
         "type": "integer"
        }
       },
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/RadianEvent"
        }
       }
      }
     },
     "402": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "409": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        },
        "examples": {
         "duplicado": {
          "summary": "Ya hay un evento vivo de ese código sobre la factura",
          "value": {
           "type": "https://platform.trevol.si/docs/errores#duplicate_document",
           "title": "Ya existe un documento igual",
           "status": 409,
           "code": "duplicate_document",
           "detail": "Esta factura ya tiene un evento 030 vivo: reintenta ese con POST /v1/radian_events/{id}/send.",
           "retryable": false,
           "existing_id": "rev_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
           "request_id": "req_5b1c5b1c5b1c5b1c5b1c5b1c"
          }
         },
         "previo": {
          "summary": "Solo en la 2026-10-21: la DIAN todavía no muestra el evento anterior",
          "value": {
           "type": "https://platform.trevol.si/docs/errores#previous_event_pending",
           "title": "Falta el evento anterior en la DIAN",
           "status": 409,
           "code": "previous_event_pending",
           "detail": "La DIAN todavía no muestra el evento 030 de esta factura: espera unos segundos y vuelve a intentarlo.",
           "retryable": true,
           "retry_after": 10,
           "previous": "030",
           "request_id": "req_5b1c5b1c5b1c5b1c5b1c5b1c"
          }
         }
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "422": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        },
        "examples": {
         "tacita": {
          "summary": "El 034 todavía no procede",
          "value": {
           "type": "https://platform.trevol.si/docs/errores#tacit_acceptance_not_due",
           "title": "La aceptación tácita todavía no procede",
           "status": 422,
           "code": "tacit_acceptance_not_due",
           "detail": "La aceptación tácita (034) todavía no procede para esta factura.",
           "retryable": false,
           "available_from": "2026-10-27",
           "rules": [
            {
             "code": "LGC14",
             "severity": "rejection",
             "local": true,
             "message": "Faltan días hábiles para la aceptación tácita.",
             "explanation": "Pasan 3 días hábiles desde el recibo del bien o servicio (evento 032)."
            }
           ],
           "request_id": "req_5b1c5b1c5b1c5b1c5b1c5b1c"
          }
         }
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "429": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "503": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       },
       "Idempotent-Replayed": {
        "$ref": "#/components/headers/Idempotent-Replayed"
       }
      }
     }
    },
    "description": "Envía un **evento RADIAN** sobre una factura: el acuse de recibo (030), el reclamo (031), el recibo del bien o servicio (032) y la aceptación expresa (033) de una factura RECIBIDA (`invoice`), o la aceptación tácita (034) de una factura PROPIA a crédito: de Trevol (`invoice_id`) o emitida antes con otro software y traída por la sincronización con la DIAN (`invoice: {cufe, number?}`; exactamente uno de los dos). Los eventos 035 a 051 necesitan un participante RADIAN y no están disponibles. El 030 y el 032 necesitan el representante legal de la empresa (lo firma): se configura en la app. **Un rechazo es final**: el siguiente intento es otro evento, con otro número (`POST` nuevo). Un evento vivo del mismo código sobre la misma factura es `409 duplicate_document` con `existing_id`: reintenta ese con `POST …/send`. `already_registered: true` (con `201`) solo significa que la DIAN ya mostraba el CUDE de ESTE evento; si la factura ya tenía ese evento por otro camino es `422 dian_rejected` con `already_registered_elsewhere: true`. La DIAN pide el evento anterior antes del siguiente: en la 2026-10-21 es `409 previous_event_pending`; en la 2026-10-22, `202 processing` y Trevol lo manda cuando aparezca. Si la DIAN contesta 98 («en proceso de validación») es `202 validating`: no reenvíes. Para saber si el 034 procede antes de pedirlo, usa `GET /v1/invoices/{id}/tacit_acceptance` (o, por CUFE, `GET /v1/radian_events/tacit_acceptance?cufe=…`).\n\n**Respuestas.** `201` la DIAN lo validó (`status: accepted`). `202` solo en la versión 2026-10-22: la DIAN no contestó (`processing`), otra petición lo está enviando (`sending`) o, en habilitación, el set de pruebas todavía lo valida (`validating`, en las dos versiones); trae `Location` y `Retry-After`, y el resultado llega por GET y por webhook: **no crees otro documento para la misma operación**. `422` `validation_error` (se revisó a fondo ANTES de reservar: no se gastó el número, y `errors[]` dice el campo), `dian_rejected` (con `document` y las reglas traducidas; un rechazo es final: el siguiente intento es otro `POST`, con otro número), `company_not_enabled` o `numbering_unavailable` (con `reason`). `402` `insufficient_balance` (producción sin saldo: queda `pending` con su número). `409` `external_id_in_use` o `duplicate_document` (con `existing_id`). `503` `dian_unavailable` en la 2026-10-21. Pide `Idempotency-Key`: repetir la misma devuelve lo mismo sin enviar nada.",
    "tags": [
     "Eventos RADIAN"
    ],
    "operationId": "createRadianEvent"
   },
   "get": {
    "summary": "Listar (evento RADIAN)",
    "parameters": [
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 100
      }
     },
     {
      "name": "starting_after",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "status",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "external_id",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "created_from",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "created_to",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "event_code",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "030",
        "031",
        "032",
        "033",
        "034"
       ],
       "description": "Solo en eventos RADIAN: el código del evento (030 a 034)."
      }
     },
     {
      "name": "invoice_cufe",
      "in": "query",
      "schema": {
       "type": "string",
       "pattern": "^[0-9a-fA-F]{96}$",
       "description": "Solo en eventos RADIAN: el CUFE de la factura sobre la que van."
      }
     }
    ],
    "responses": {
     "200": {
      "description": "{object: list, data, has_more, next_cursor}",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "object",
          "data",
          "has_more",
          "next_cursor"
         ],
         "properties": {
          "object": {
           "type": "string",
           "enum": [
            "list"
           ]
          },
          "data": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/RadianEvent"
           }
          },
          "has_more": {
           "type": "boolean"
          },
          "next_cursor": {
           "type": [
            "string",
            "null"
           ]
          }
         }
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "Paginación por cursor y filtros `status`, `external_id`, `created_from`, `created_to`, `event_code` y `invoice_cufe` (el CUFE de la factura).",
    "tags": [
     "Eventos RADIAN"
    ],
    "operationId": "listRadianEvents"
   }
  },
  "/radian_events/{id}": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Un evento radian",
    "responses": {
     "200": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/RadianEvent"
        },
        "example": {
         "id": "rev_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
         "object": "radian_event",
         "environment": "test",
         "status": "accepted",
         "event_code": "030",
         "number": "AR994000123",
         "prefix": "AR",
         "external_id": "ERP-ACUSE-OJ1234",
         "origin": "api",
         "cude": "abababababababababababababababababababababababababababababababababababababababababababababababab",
         "issued_at": "2026-10-23T09:15:02-05:00",
         "invoice": {
          "cufe": "cdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd",
          "number": "OJ1234",
          "type": "01",
          "issuer": {
           "nit": "890330031",
           "check_digit": 3,
           "document_type": "31",
           "name": "OSPINA Y ASOCIADOS SAS"
          }
         },
         "claim": null,
         "software": "own",
         "provider": "company",
         "dian": {
          "status_code": "02",
          "message": "Documento validado por la DIAN",
          "rules": []
         },
         "already_registered": false,
         "already_registered_elsewhere": false,
         "tacit": false,
         "created_at": "2026-10-23T09:15:02-05:00",
         "updated_at": "2026-10-23T09:15:03-05:00"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "El evento tal como se envió, con su número, su CUDE, la factura y la respuesta de la DIAN. `already_registered`, `already_registered_elsewhere` y `tacit` se deducen de lo guardado.",
    "tags": [
     "Eventos RADIAN"
    ],
    "operationId": "retrieveRadianEvent"
   }
  },
  "/radian_events/{id}/send": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "post": {
    "summary": "Reenviar una pendiente o en error",
    "parameters": [
     {
      "name": "Trevol-Version",
      "in": "header",
      "required": false,
      "description": "La versión de la API. Si no viene, la de la llave (las llaves de antes quedan en 2026-10-21; las nuevas nacen en 2026-10-22).",
      "schema": {
       "type": "string",
       "enum": [
        "2026-10-21",
        "2026-10-22"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "El documento",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/RadianEvent"
        },
        "example": {
         "id": "rev_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
         "object": "radian_event",
         "environment": "test",
         "status": "accepted",
         "event_code": "030",
         "number": "AR994000123",
         "prefix": "AR",
         "external_id": "ERP-ACUSE-OJ1234",
         "origin": "api",
         "cude": "abababababababababababababababababababababababababababababababababababababababababababababababab",
         "issued_at": "2026-10-23T09:15:02-05:00",
         "invoice": {
          "cufe": "cdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd",
          "number": "OJ1234",
          "type": "01",
          "issuer": {
           "nit": "890330031",
           "check_digit": 3,
           "document_type": "31",
           "name": "OSPINA Y ASOCIADOS SAS"
          }
         },
         "claim": null,
         "software": "own",
         "provider": "company",
         "dian": {
          "status_code": "02",
          "message": "Documento validado por la DIAN",
          "rules": []
         },
         "already_registered": false,
         "already_registered_elsewhere": false,
         "tacit": false,
         "created_at": "2026-10-23T09:15:02-05:00",
         "updated_at": "2026-10-23T09:15:03-05:00"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "202": {
      "description": "Versión 2026-10-22: la DIAN no contestó (`status: processing`; Trevol termina el documento y avisa por webhook; no crees otro documento para la misma venta, y si repites con la misma Idempotency-Key respondemos sin enviar) o el documento se está enviando (`status: sending`); también la contingencia (`status: contingency`). Lleva `Location` y, salvo la contingencia, `Retry-After: 30`. En 2026-10-21 la DIAN sin contestar es un 503 `dian_unavailable`. También `status: validating` (en las dos versiones): la DIAN respondió 98; reintentar con la misma Idempotency-Key o `POST …/send` responde lo mismo SIN reenviar. En la 2026-10-21, el evento anterior que aún no aparece es 409 `previous_event_pending`.",
      "headers": {
       "Location": {
        "schema": {
         "type": "string"
        }
       },
       "Retry-After": {
        "schema": {
         "type": "integer"
        }
       },
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/RadianEvent"
        }
       }
      }
     },
     "409": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "Vuelve a enviar un evento `pending` o `error` con el **mismo número** (por ejemplo, un 034 que todavía no procedía o un 031 que esperaba al evento anterior). Un evento que la DIAN verifica (`validating`) solo consulta; uno `rejected` es final (`409 invalid_state`): crea otro con `POST`.\n\nSin cuerpo. Con un documento `accepted` responde `200` con el documento tal cual; con uno que la DIAN todavía verifica no reenvía nada (`202`); con uno `rejected` es `409 invalid_state` (se corrige con `PUT`). No pide `Idempotency-Key` (reintentarlo es seguro).",
    "tags": [
     "Eventos RADIAN"
    ],
    "operationId": "sendRadianEvent"
   }
  },
  "/radian_events/{id}/xml": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "Archivo xml",
    "responses": {
     "200": {
      "description": "xml",
      "content": {
       "application/xml": {
        "schema": {
         "type": "string",
         "format": "binary"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "description": "El ApplicationResponse firmado que se mandó a la DIAN (`application/xml`). Los eventos no tienen PDF, ZIP ni `dian_response`.",
    "tags": [
     "Eventos RADIAN"
    ],
    "operationId": "downloadRadianEventXml"
   }
  },
  "/invoices/{id}/tacit_acceptance": {
   "parameters": [
    {
     "name": "id",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "summary": "¿Procede ya la aceptación tácita (034) de esta factura?",
    "description": "Consulta GetStatusEvent (con el certificado de la empresa) y aplica la regla de los 3 días hábiles; no envía nada. Usa el mismo historial que el envío del 034 (`POST /v1/radian_events`), así que la consulta y el envío no se contradicen. 404 si la factura no es de la empresa y el ambiente de la llave; 422 si no está validada, no es a crédito o es de consumidor final; 429 con más de 30 consultas por minuto por llave; 503 si la DIAN no contesta (reintentable).",
    "responses": {
     "200": {
      "description": "El resultado",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/TacitAcceptance"
        },
        "example": {
         "object": "tacit_acceptance",
         "invoice_id": "inv_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
         "cufe": "abababababababababababababababababababababababababababababababababababababababababababababababab",
         "number": "FE1234",
         "allowed": false,
         "available_from": "2026-10-27",
         "rules": [
          {
           "code": "LGC14",
           "severity": "rejection",
           "local": true,
           "message": "Faltan días hábiles para la aceptación tácita.",
           "explanation": "Pasan 3 días hábiles desde el recibo del bien o servicio (evento 032)."
          }
         ]
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Facturas"
    ],
    "operationId": "retrieveInvoiceTacitAcceptance"
   }
  },
  "/radian_events/tacit_acceptance": {
   "get": {
    "summary": "¿Procede ya la aceptación tácita (034) de esta factura? (por CUFE)",
    "description": "Lo mismo que `GET /v1/invoices/{id}/tacit_acceptance`, pero por el CUFE de la factura propia: sirve también para las facturas que no se emitieron con Trevol (emitidas antes, con otro software, y traídas por la sincronización con la DIAN; la sincronización trae las de producción). Consulta GetStatusEvent y aplica la regla de los 3 días hábiles; no envía nada. `invoice_id` solo sale si la factura es de Trevol. 404 si el CUFE no es de una factura propia de la empresa y el ambiente de la llave; 422 si falta `cufe` o la factura no admite el 034 (de contado, una nota, a consumidor final, sin el XML leído por la sincronización…); 429 con más de 30 consultas por minuto por llave (el mismo límite de la otra consulta); 503 si la DIAN no contesta (reintentable).",
    "parameters": [
     {
      "name": "cufe",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^[0-9a-fA-F]{96}$"
      },
      "description": "El CUFE de la factura propia."
     }
    ],
    "responses": {
     "200": {
      "description": "El resultado",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/TacitAcceptance"
        },
        "example": {
         "object": "tacit_acceptance",
         "cufe": "abababababababababababababababababababababababababababababababababababababababababababababababab",
         "number": "FE4722",
         "allowed": true,
         "available_from": "2025-05-14",
         "rules": []
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     },
     "default": {
      "description": "Error (application/problem+json)",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      },
      "headers": {
       "Request-Id": {
        "$ref": "#/components/headers/Request-Id"
       },
       "Trevol-Version": {
        "$ref": "#/components/headers/Trevol-Version"
       }
      }
     }
    },
    "tags": [
     "Eventos RADIAN"
    ],
    "operationId": "retrieveTacitAcceptanceByCufe"
   }
  }
 },
 "webhooks": {
  "invoice.accepted": {
   "post": {
    "summary": "Evento invoice.accepted",
    "description": "La DIAN validó la factura. Pasa por cualquier camino (API, app, conector o verificación de fondo).",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "invoice.accepted"
           },
           "data": {
            "$ref": "#/components/schemas/DocumentEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "invoice.rejected": {
   "post": {
    "summary": "Evento invoice.rejected",
    "description": "La DIAN rechazó la factura. Corrígela con PUT y se reenvía con el mismo número.",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "invoice.rejected"
           },
           "data": {
            "$ref": "#/components/schemas/DocumentEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "invoice.error": {
   "post": {
    "summary": "Evento invoice.error",
    "description": "La factura quedó en error: la DIAN no confirmó y Trevol dejó de reintentar. `data.error` lleva un `code` y un texto fijo (nunca el mensaje de la DIAN).",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "invoice.error"
           },
           "data": {
            "$ref": "#/components/schemas/DocumentEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "invoice.delivered": {
   "post": {
    "summary": "Evento invoice.delivered",
    "description": "La factura ya tiene PDF, ZIP y un correo en estado final (la primera vez).",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "invoice.delivered"
           },
           "data": {
            "$ref": "#/components/schemas/DocumentEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "invoice.email_bounced": {
   "post": {
    "summary": "Evento invoice.email_bounced",
    "description": "El correo de la factura rebotó o el comprador lo marcó como queja (`delivery.email.status`: `bounced` o `complained`).",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "invoice.email_bounced"
           },
           "data": {
            "$ref": "#/components/schemas/DocumentEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "invoice.email_failed": {
   "post": {
    "summary": "Evento invoice.email_failed",
    "description": "El correo de la factura falló de forma definitiva (`delivery.email.status`: `failed`).",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "invoice.email_failed"
           },
           "data": {
            "$ref": "#/components/schemas/DocumentEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "credit_note.accepted": {
   "post": {
    "summary": "Evento credit_note.accepted",
    "description": "La DIAN validó la nota crédito. Pasa por cualquier camino (API, app, conector o verificación de fondo).",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "credit_note.accepted"
           },
           "data": {
            "$ref": "#/components/schemas/DocumentEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "credit_note.rejected": {
   "post": {
    "summary": "Evento credit_note.rejected",
    "description": "La DIAN rechazó la nota crédito. Corrígela con PUT y se reenvía con el mismo número.",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "credit_note.rejected"
           },
           "data": {
            "$ref": "#/components/schemas/DocumentEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "credit_note.error": {
   "post": {
    "summary": "Evento credit_note.error",
    "description": "La nota crédito quedó en error: la DIAN no confirmó y Trevol dejó de reintentar. `data.error` lleva un `code` y un texto fijo (nunca el mensaje de la DIAN).",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "credit_note.error"
           },
           "data": {
            "$ref": "#/components/schemas/DocumentEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "credit_note.delivered": {
   "post": {
    "summary": "Evento credit_note.delivered",
    "description": "La nota crédito ya tiene PDF, ZIP y un correo en estado final (la primera vez).",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "credit_note.delivered"
           },
           "data": {
            "$ref": "#/components/schemas/DocumentEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "credit_note.email_bounced": {
   "post": {
    "summary": "Evento credit_note.email_bounced",
    "description": "El correo de la nota crédito rebotó o el comprador lo marcó como queja (`delivery.email.status`: `bounced` o `complained`).",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "credit_note.email_bounced"
           },
           "data": {
            "$ref": "#/components/schemas/DocumentEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "credit_note.email_failed": {
   "post": {
    "summary": "Evento credit_note.email_failed",
    "description": "El correo de la nota crédito falló de forma definitiva (`delivery.email.status`: `failed`).",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "credit_note.email_failed"
           },
           "data": {
            "$ref": "#/components/schemas/DocumentEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "debit_note.accepted": {
   "post": {
    "summary": "Evento debit_note.accepted",
    "description": "La DIAN validó la nota débito. Pasa por cualquier camino (API, app, conector o verificación de fondo).",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "debit_note.accepted"
           },
           "data": {
            "$ref": "#/components/schemas/DocumentEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "debit_note.rejected": {
   "post": {
    "summary": "Evento debit_note.rejected",
    "description": "La DIAN rechazó la nota débito. Corrígela con PUT y se reenvía con el mismo número.",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "debit_note.rejected"
           },
           "data": {
            "$ref": "#/components/schemas/DocumentEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "debit_note.error": {
   "post": {
    "summary": "Evento debit_note.error",
    "description": "La nota débito quedó en error: la DIAN no confirmó y Trevol dejó de reintentar. `data.error` lleva un `code` y un texto fijo (nunca el mensaje de la DIAN).",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "debit_note.error"
           },
           "data": {
            "$ref": "#/components/schemas/DocumentEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "debit_note.delivered": {
   "post": {
    "summary": "Evento debit_note.delivered",
    "description": "La nota débito ya tiene PDF, ZIP y un correo en estado final (la primera vez).",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "debit_note.delivered"
           },
           "data": {
            "$ref": "#/components/schemas/DocumentEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "debit_note.email_bounced": {
   "post": {
    "summary": "Evento debit_note.email_bounced",
    "description": "El correo de la nota débito rebotó o el comprador lo marcó como queja (`delivery.email.status`: `bounced` o `complained`).",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "debit_note.email_bounced"
           },
           "data": {
            "$ref": "#/components/schemas/DocumentEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "debit_note.email_failed": {
   "post": {
    "summary": "Evento debit_note.email_failed",
    "description": "El correo de la nota débito falló de forma definitiva (`delivery.email.status`: `failed`).",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "debit_note.email_failed"
           },
           "data": {
            "$ref": "#/components/schemas/DocumentEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "balance.low": {
   "post": {
    "summary": "Evento balance.low",
    "description": "El saldo de la cuenta quedó bajo o se agotó (`data.level`). Solo producción: te llega a cada empresa de la cuenta.",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "balance.low"
           },
           "data": {
            "$ref": "#/components/schemas/BalanceEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "numbering.low": {
   "post": {
    "summary": "Evento numbering.low",
    "description": "A una resolución de numeración le quedan pocos números. Solo producción.",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "numbering.low"
           },
           "data": {
            "$ref": "#/components/schemas/NumberingLowEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "numbering.expiring": {
   "post": {
    "summary": "Evento numbering.expiring",
    "description": "Una resolución de numeración vence en 30 y en 7 días. Solo producción.",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "numbering.expiring"
           },
           "data": {
            "$ref": "#/components/schemas/NumberingExpiringEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "certificate.expiring": {
   "post": {
    "summary": "Evento certificate.expiring",
    "description": "El certificado de firma de la empresa vence en 30, 15, 7 y 1 día. Los dos ambientes.",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "certificate.expiring"
           },
           "data": {
            "$ref": "#/components/schemas/CertificateEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "support_document.accepted": {
   "post": {
    "summary": "Evento support_document.accepted",
    "description": "La DIAN validó el documento soporte. Pasa por cualquier camino (API, app, conector o verificación de fondo). (Catálogo 2: un `*` de un endpoint creado antes de la fase 3 no lo recibe hasta que se guarde de nuevo su lista de eventos.)",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "support_document.accepted"
           },
           "data": {
            "$ref": "#/components/schemas/SupportDocumentEventData"
           }
          }
         }
        ]
       },
       "example": {
        "id": "evt_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
        "object": "event",
        "type": "support_document.accepted",
        "timestamp": "2026-10-23T14:15:03Z",
        "environment": "test",
        "api_version": "2026-10-22",
        "data": {
         "object": "support_document",
         "id": "sd_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
         "status": "accepted",
         "environment": "test",
         "number": "DS994001",
         "prefix": "DS",
         "external_id": "OC-991",
         "origin": "api",
         "cuds": "abababababababababababababababababababababababababababababababababababababababababababababababab",
         "issued_at": "2026-10-23T09:15:02-05:00",
         "total": "216000.00",
         "delivery": null,
         "dian": {
          "status_code": "00",
          "rules": []
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "support_document.rejected": {
   "post": {
    "summary": "Evento support_document.rejected",
    "description": "La DIAN rechazó el documento soporte. Corrígela con PUT y se reenvía con el mismo número. (Catálogo 2: un `*` de un endpoint creado antes de la fase 3 no lo recibe hasta que se guarde de nuevo su lista de eventos.)",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "support_document.rejected"
           },
           "data": {
            "$ref": "#/components/schemas/SupportDocumentEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "support_document.error": {
   "post": {
    "summary": "Evento support_document.error",
    "description": "El documento soporte quedó en error: la DIAN no confirmó y Trevol dejó de reintentar. `data.error` lleva un `code` y un texto fijo (nunca el mensaje de la DIAN). (Catálogo 2: un `*` de un endpoint creado antes de la fase 3 no lo recibe hasta que se guarde de nuevo su lista de eventos.)",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "support_document.error"
           },
           "data": {
            "$ref": "#/components/schemas/SupportDocumentEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "support_document_adjustment.accepted": {
   "post": {
    "summary": "Evento support_document_adjustment.accepted",
    "description": "La DIAN validó la nota de ajuste del documento soporte. Pasa por cualquier camino (API, app, conector o verificación de fondo). (Catálogo 2: un `*` de un endpoint creado antes de la fase 3 no lo recibe hasta que se guarde de nuevo su lista de eventos.)",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "support_document_adjustment.accepted"
           },
           "data": {
            "$ref": "#/components/schemas/SupportDocumentEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "support_document_adjustment.rejected": {
   "post": {
    "summary": "Evento support_document_adjustment.rejected",
    "description": "La DIAN rechazó la nota de ajuste del documento soporte. Corrígela con PUT y se reenvía con el mismo número. (Catálogo 2: un `*` de un endpoint creado antes de la fase 3 no lo recibe hasta que se guarde de nuevo su lista de eventos.)",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "support_document_adjustment.rejected"
           },
           "data": {
            "$ref": "#/components/schemas/SupportDocumentEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "support_document_adjustment.error": {
   "post": {
    "summary": "Evento support_document_adjustment.error",
    "description": "La nota de ajuste del documento soporte quedó en error: la DIAN no confirmó y Trevol dejó de reintentar. `data.error` lleva un `code` y un texto fijo (nunca el mensaje de la DIAN). (Catálogo 2: un `*` de un endpoint creado antes de la fase 3 no lo recibe hasta que se guarde de nuevo su lista de eventos.)",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "support_document_adjustment.error"
           },
           "data": {
            "$ref": "#/components/schemas/SupportDocumentEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "equivalent_document.accepted": {
   "post": {
    "summary": "Evento equivalent_document.accepted",
    "description": "La DIAN validó el documento equivalente. Pasa por cualquier camino (API, app, conector o verificación de fondo). (Catálogo 2: un `*` de un endpoint creado antes de la fase 3 no lo recibe hasta que se guarde de nuevo su lista de eventos.)",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "equivalent_document.accepted"
           },
           "data": {
            "$ref": "#/components/schemas/EquivalentDocumentEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "equivalent_document.rejected": {
   "post": {
    "summary": "Evento equivalent_document.rejected",
    "description": "La DIAN rechazó el documento equivalente. Corrígela con PUT y se reenvía con el mismo número. (Catálogo 2: un `*` de un endpoint creado antes de la fase 3 no lo recibe hasta que se guarde de nuevo su lista de eventos.)",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "equivalent_document.rejected"
           },
           "data": {
            "$ref": "#/components/schemas/EquivalentDocumentEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "equivalent_document.error": {
   "post": {
    "summary": "Evento equivalent_document.error",
    "description": "El documento equivalente quedó en error: la DIAN no confirmó y Trevol dejó de reintentar. `data.error` lleva un `code` y un texto fijo (nunca el mensaje de la DIAN). (Catálogo 2: un `*` de un endpoint creado antes de la fase 3 no lo recibe hasta que se guarde de nuevo su lista de eventos.)",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "equivalent_document.error"
           },
           "data": {
            "$ref": "#/components/schemas/EquivalentDocumentEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "equivalent_document.delivered": {
   "post": {
    "summary": "Evento equivalent_document.delivered",
    "description": "El documento equivalente ya tiene PDF, ZIP y un correo en estado final (la primera vez). (Catálogo 2: un `*` de un endpoint creado antes de la fase 3 no lo recibe hasta que se guarde de nuevo su lista de eventos.)",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "equivalent_document.delivered"
           },
           "data": {
            "$ref": "#/components/schemas/EquivalentDocumentEventData"
           }
          }
         }
        ]
       },
       "example": {
        "id": "evt_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
        "object": "event",
        "type": "equivalent_document.delivered",
        "timestamp": "2026-10-23T14:15:03Z",
        "environment": "test",
        "api_version": "2026-10-22",
        "data": {
         "object": "equivalent_document",
         "id": "pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
         "status": "accepted",
         "environment": "test",
         "number": "POS2994001",
         "prefix": "POS2",
         "external_id": "TIQ-1",
         "origin": "api",
         "cude": "abababababababababababababababababababababababababababababababababababababababababababababababab",
         "issued_at": "2026-10-23T09:15:02-05:00",
         "total": "25140.00",
         "document_type": "20",
         "dian": {
          "status_code": "00",
          "rules": []
         },
         "delivery": {
          "pdf": true,
          "zip": true,
          "email": {
           "status": "sent"
          }
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "equivalent_document.email_bounced": {
   "post": {
    "summary": "Evento equivalent_document.email_bounced",
    "description": "El correo de el documento equivalente rebotó o el comprador lo marcó como queja (`delivery.email.status`: `bounced` o `complained`). (Catálogo 2: un `*` de un endpoint creado antes de la fase 3 no lo recibe hasta que se guarde de nuevo su lista de eventos.)",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "equivalent_document.email_bounced"
           },
           "data": {
            "$ref": "#/components/schemas/EquivalentDocumentEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "equivalent_document.email_failed": {
   "post": {
    "summary": "Evento equivalent_document.email_failed",
    "description": "El correo de el documento equivalente falló de forma definitiva (`delivery.email.status`: `failed`). (Catálogo 2: un `*` de un endpoint creado antes de la fase 3 no lo recibe hasta que se guarde de nuevo su lista de eventos.)",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "equivalent_document.email_failed"
           },
           "data": {
            "$ref": "#/components/schemas/EquivalentDocumentEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "equivalent_document_adjustment.accepted": {
   "post": {
    "summary": "Evento equivalent_document_adjustment.accepted",
    "description": "La DIAN validó la nota de ajuste del documento equivalente. Pasa por cualquier camino (API, app, conector o verificación de fondo). (Catálogo 2: un `*` de un endpoint creado antes de la fase 3 no lo recibe hasta que se guarde de nuevo su lista de eventos.)",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "equivalent_document_adjustment.accepted"
           },
           "data": {
            "$ref": "#/components/schemas/EquivalentDocumentEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "equivalent_document_adjustment.rejected": {
   "post": {
    "summary": "Evento equivalent_document_adjustment.rejected",
    "description": "La DIAN rechazó la nota de ajuste del documento equivalente. Corrígela con PUT y se reenvía con el mismo número. (Catálogo 2: un `*` de un endpoint creado antes de la fase 3 no lo recibe hasta que se guarde de nuevo su lista de eventos.)",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "equivalent_document_adjustment.rejected"
           },
           "data": {
            "$ref": "#/components/schemas/EquivalentDocumentEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "equivalent_document_adjustment.error": {
   "post": {
    "summary": "Evento equivalent_document_adjustment.error",
    "description": "La nota de ajuste del documento equivalente quedó en error: la DIAN no confirmó y Trevol dejó de reintentar. `data.error` lleva un `code` y un texto fijo (nunca el mensaje de la DIAN). (Catálogo 2: un `*` de un endpoint creado antes de la fase 3 no lo recibe hasta que se guarde de nuevo su lista de eventos.)",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "equivalent_document_adjustment.error"
           },
           "data": {
            "$ref": "#/components/schemas/EquivalentDocumentEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "equivalent_document_adjustment.delivered": {
   "post": {
    "summary": "Evento equivalent_document_adjustment.delivered",
    "description": "La nota de ajuste del documento equivalente ya tiene PDF, ZIP y un correo en estado final (la primera vez). (Catálogo 2: un `*` de un endpoint creado antes de la fase 3 no lo recibe hasta que se guarde de nuevo su lista de eventos.)",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "equivalent_document_adjustment.delivered"
           },
           "data": {
            "$ref": "#/components/schemas/EquivalentDocumentEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "equivalent_document_adjustment.email_bounced": {
   "post": {
    "summary": "Evento equivalent_document_adjustment.email_bounced",
    "description": "El correo de la nota de ajuste del documento equivalente rebotó o el comprador lo marcó como queja (`delivery.email.status`: `bounced` o `complained`). (Catálogo 2: un `*` de un endpoint creado antes de la fase 3 no lo recibe hasta que se guarde de nuevo su lista de eventos.)",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "equivalent_document_adjustment.email_bounced"
           },
           "data": {
            "$ref": "#/components/schemas/EquivalentDocumentEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "equivalent_document_adjustment.email_failed": {
   "post": {
    "summary": "Evento equivalent_document_adjustment.email_failed",
    "description": "El correo de la nota de ajuste del documento equivalente falló de forma definitiva (`delivery.email.status`: `failed`). (Catálogo 2: un `*` de un endpoint creado antes de la fase 3 no lo recibe hasta que se guarde de nuevo su lista de eventos.)",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "equivalent_document_adjustment.email_failed"
           },
           "data": {
            "$ref": "#/components/schemas/EquivalentDocumentEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "payroll.accepted": {
   "post": {
    "summary": "Evento payroll.accepted",
    "description": "La DIAN validó la nómina electrónica. Pasa por cualquier camino (API, app, conector o verificación de fondo). (Catálogo 2: un `*` de un endpoint creado antes de la fase 3 no lo recibe hasta que se guarde de nuevo su lista de eventos.)",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "payroll.accepted"
           },
           "data": {
            "$ref": "#/components/schemas/PayrollEventData"
           }
          }
         }
        ]
       },
       "example": {
        "id": "evt_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
        "object": "event",
        "type": "payroll.accepted",
        "timestamp": "2026-10-23T14:15:03Z",
        "environment": "live",
        "api_version": "2026-10-22",
        "data": {
         "object": "payroll",
         "id": "pr_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
         "status": "accepted",
         "environment": "live",
         "number": "NE15",
         "prefix": "NE",
         "external_id": "NOM-2026-09-001",
         "origin": "api",
         "cune": "abababababababababababababababababababababababababababababababababababababababababababababababab",
         "issued_at": "2026-10-23T09:15:02-05:00",
         "type": null,
         "predecessor": null,
         "submission": "sync",
         "dian": {
          "status_code": "00",
          "rules": [
           {
            "code": "NIE038",
            "severity": "notification"
           }
          ]
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "payroll.rejected": {
   "post": {
    "summary": "Evento payroll.rejected",
    "description": "La DIAN rechazó la nómina electrónica. Corrígela con PUT y se reenvía con el mismo número. (Catálogo 2: un `*` de un endpoint creado antes de la fase 3 no lo recibe hasta que se guarde de nuevo su lista de eventos.)",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "payroll.rejected"
           },
           "data": {
            "$ref": "#/components/schemas/PayrollEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "payroll.error": {
   "post": {
    "summary": "Evento payroll.error",
    "description": "La nómina electrónica quedó en error: la DIAN no confirmó y Trevol dejó de reintentar. `data.error` lleva un `code` y un texto fijo (nunca el mensaje de la DIAN). (Catálogo 2: un `*` de un endpoint creado antes de la fase 3 no lo recibe hasta que se guarde de nuevo su lista de eventos.)",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "payroll.error"
           },
           "data": {
            "$ref": "#/components/schemas/PayrollEventData"
           }
          }
         }
        ]
       },
       "example": {
        "id": "evt_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
        "object": "event",
        "type": "payroll.error",
        "timestamp": "2026-10-23T14:15:03Z",
        "environment": "live",
        "api_version": "2026-10-22",
        "data": {
         "object": "payroll",
         "id": "pr_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
         "status": "error",
         "environment": "live",
         "number": "NE15",
         "prefix": "NE",
         "external_id": "NOM-2026-09-001",
         "origin": "api",
         "cune": null,
         "issued_at": null,
         "type": null,
         "predecessor": null,
         "submission": "sync",
         "dian": {
          "status_code": null,
          "rules": []
         },
         "error": {
          "code": "dian_unavailable",
          "message": "La DIAN no confirmó el documento a tiempo; reenvíalo."
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "payroll_adjustment.accepted": {
   "post": {
    "summary": "Evento payroll_adjustment.accepted",
    "description": "La DIAN validó la nota de ajuste de nómina. Pasa por cualquier camino (API, app, conector o verificación de fondo). (Catálogo 2: un `*` de un endpoint creado antes de la fase 3 no lo recibe hasta que se guarde de nuevo su lista de eventos.)",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "payroll_adjustment.accepted"
           },
           "data": {
            "$ref": "#/components/schemas/PayrollEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "payroll_adjustment.rejected": {
   "post": {
    "summary": "Evento payroll_adjustment.rejected",
    "description": "La DIAN rechazó la nota de ajuste de nómina. Corrígela con PUT y se reenvía con el mismo número. (Catálogo 2: un `*` de un endpoint creado antes de la fase 3 no lo recibe hasta que se guarde de nuevo su lista de eventos.)",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "payroll_adjustment.rejected"
           },
           "data": {
            "$ref": "#/components/schemas/PayrollEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "payroll_adjustment.error": {
   "post": {
    "summary": "Evento payroll_adjustment.error",
    "description": "La nota de ajuste de nómina quedó en error: la DIAN no confirmó y Trevol dejó de reintentar. `data.error` lleva un `code` y un texto fijo (nunca el mensaje de la DIAN). (Catálogo 2: un `*` de un endpoint creado antes de la fase 3 no lo recibe hasta que se guarde de nuevo su lista de eventos.)",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "payroll_adjustment.error"
           },
           "data": {
            "$ref": "#/components/schemas/PayrollEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "radian_event.accepted": {
   "post": {
    "summary": "Evento radian_event.accepted",
    "description": "La DIAN validó el evento RADIAN. Pasa por cualquier camino (API, app, conector o verificación de fondo). (Catálogo 2: un `*` de un endpoint creado antes de la fase 3 no lo recibe hasta que se guarde de nuevo su lista de eventos.)",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "radian_event.accepted"
           },
           "data": {
            "$ref": "#/components/schemas/RadianEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "radian_event.rejected": {
   "post": {
    "summary": "Evento radian_event.rejected",
    "description": "La DIAN rechazó el evento. Un rechazo es final: el siguiente intento es otro `POST /v1/radian_events` (otro número). (Catálogo 2: un `*` de un endpoint creado antes de la fase 3 no lo recibe hasta que se guarde de nuevo su lista de eventos.)",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "radian_event.rejected"
           },
           "data": {
            "$ref": "#/components/schemas/RadianEventData"
           }
          }
         }
        ]
       },
       "example": {
        "id": "evt_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
        "object": "event",
        "type": "radian_event.rejected",
        "timestamp": "2026-10-23T14:15:03Z",
        "environment": "test",
        "api_version": "2026-10-22",
        "data": {
         "object": "radian_event",
         "id": "rev_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
         "status": "rejected",
         "environment": "test",
         "event_code": "031",
         "number": "RC994000124",
         "prefix": "RC",
         "external_id": "ERP-RECLAMO-OJ1234",
         "origin": "api",
         "cude": "abababababababababababababababababababababababababababababababababababababababababababababababab",
         "issued_at": "2026-10-23T09:15:02-05:00",
         "invoice": {
          "cufe": "cdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd",
          "number": "OJ1234",
          "id": null
         },
         "dian": {
          "status_code": "99",
          "rules": [
           {
            "code": "LGC09",
            "severity": "rejection"
           }
          ]
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "radian_event.error": {
   "post": {
    "summary": "Evento radian_event.error",
    "description": "El evento quedó en error: la DIAN no confirmó y Trevol dejó de reintentar. `data.error` lleva un `code` y un texto fijo. Reenvíalo con `POST …/send`. (Catálogo 2: un `*` de un endpoint creado antes de la fase 3 no lo recibe hasta que se guarde de nuevo su lista de eventos.)",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "radian_event.error"
           },
           "data": {
            "$ref": "#/components/schemas/RadianEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  },
  "webhook.test": {
   "post": {
    "summary": "Evento webhook.test",
    "description": "Lo manda POST …/test (o «Probar» en la app) solo a ese endpoint. No se suscribe.",
    "tags": [
     "Webhooks"
    ],
    "parameters": [
     {
      "name": "webhook-id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^evt_[0-9a-f]{32}$"
      },
      "description": "El id del evento. Es el mismo en cada reintento y en un reenvío manual: deduplica con él."
     },
     {
      "name": "webhook-timestamp",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "Segundos Unix del INTENTO (cambia en cada reintento). Rechaza los que tengan más de 5 minutos de diferencia."
     },
     {
      "name": "webhook-signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "`v1,` + base64(HMAC-SHA256(clave, `{webhook-id}.{webhook-timestamp}.{cuerpo}`)). La clave son los 32 bytes que siguen a `whsec_` (en base64). Durante la gracia de una rotación trae dos firmas separadas por un espacio: basta con que una coincida. Calcúlala sobre el cuerpo tal como llegó."
     },
     {
      "name": "user-agent",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Event"
         },
         {
          "type": "object",
          "properties": {
           "type": {
            "const": "webhook.test"
           },
           "data": {
            "$ref": "#/components/schemas/TestEventData"
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cualquier 2xx en 10 segundos cuenta como entregado. El cuerpo de tu respuesta no se guarda."
     },
     "default": {
      "description": "Un 3xx (no se siguen redirecciones), un 4xx, un 5xx, un tiempo agotado o un error de TLS cuentan como fallo: se reintenta 8 veces en unas 32 horas (1 min, 5 min, 30 min, 2 h, 5 h, 10 h y 14 h). Con fallos durante 5 días el endpoint se desactiva y te avisamos por correo."
     }
    }
   }
  }
 },
 "components": {
  "securitySchemes": {
   "llave": {
    "type": "http",
    "scheme": "bearer",
    "description": "tvl_test_… o tvl_live_…"
   }
  },
  "headers": {
   "Request-Id": {
    "description": "El id de esta petición (`req_…`): dilo al pedir ayuda y búscalo en `GET /v1/requests`.",
    "schema": {
     "type": "string",
     "pattern": "^req_[0-9a-f]{24}$"
    }
   },
   "Trevol-Version": {
    "description": "La versión de la API con que se atendió la petición (la de `Trevol-Version`, o la de la llave).",
    "schema": {
     "type": "string",
     "enum": [
      "2026-10-21",
      "2026-10-22"
     ]
    }
   },
   "Idempotent-Replayed": {
    "description": "`true` si la respuesta es la guardada por una petición anterior con la misma `Idempotency-Key` (no se volvió a ejecutar).",
    "schema": {
     "type": "string",
     "enum": [
      "true"
     ]
    }
   }
  },
  "schemas": {
   "Customer": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "final_consumer": {
      "type": "boolean"
     },
     "document_type": {
      "type": "string",
      "maxLength": 20,
      "description": "Tipo de documento (tabla 13.2.1 de la DIAN): 13 CC, 31 NIT, 22 CE, 41 PA…"
     },
     "document_number": {
      "type": "string",
      "description": "Sin DV ni puntos; el DV lo calcula Trevol."
     },
     "check_digit": {
      "type": "integer",
      "description": "Opcional: si viene, tiene que ser el DV del NIT."
     },
     "name": {
      "type": "string"
     },
     "person_type": {
      "type": "string",
      "enum": [
       "legal",
       "natural"
      ],
      "description": "Por defecto se deduce del NIT."
     },
     "email": {
      "type": "string"
     },
     "phone": {
      "type": "string"
     },
     "address": {
      "type": "string"
     },
     "city": {
      "type": "string"
     },
     "municipality_code": {
      "type": "string",
      "maxLength": 20,
      "description": "Código DANE del municipio (5 dígitos)."
     },
     "department_code": {
      "type": "string",
      "maxLength": 20
     },
     "tax_responsibilities": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "maxItems": 20,
      "description": "Tabla 13.2.6.1 (O-13, O-15, O-23, O-47, R-99-PN)."
     },
     "tax_scheme": {
      "type": "string",
      "maxLength": 20,
      "description": "TaxScheme del adquiriente: 01, 04, ZA o ZZ (por defecto ZZ)."
     },
     "country": {
      "type": "string",
      "maxLength": 20,
      "description": "País del cliente (tabla 13.4.1, ISO 3166-1 alfa-2). Distinto de \"CO\": cliente en el exterior, sin `municipality_code`; con `city`, `region` y `postal_code`. Solo en facturas."
     },
     "region": {
      "type": "string",
      "description": "Departamento, estado o provincia del cliente en el exterior. Solo en facturas."
     },
     "region_code": {
      "type": "string",
      "maxLength": 20,
      "description": "Código de la región del cliente en el exterior (máximo 6). Solo en facturas."
     },
     "postal_code": {
      "type": "string",
      "maxLength": 20,
      "description": "Código postal del cliente en el exterior (máximo 10). Solo en facturas."
     }
    }
   },
   "ItemTax": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "code": {
      "type": "string",
      "maxLength": 20,
      "description": "Código (texto)."
     },
     "rate": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Tarifa en % (ICA y ReteICA: por mil)."
     },
     "excluded": {
      "type": "boolean"
     },
     "unit_amount": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "unit": {
      "type": "string",
      "maxLength": 20,
      "description": "Unidad de medida (tabla 13.3.6). Por defecto 94 (unidad)."
     },
     "quantity": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "volume_cc": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "name": {
      "type": "string"
     }
    },
    "required": [
     "code"
    ]
   },
   "ItemAllowance": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "code": {
      "type": "string",
      "maxLength": 20,
      "description": "Código (texto)."
     },
     "reason": {
      "type": "string"
     },
     "percent": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "amount": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     }
    }
   },
   "ItemWithholding": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "code": {
      "type": "string",
      "maxLength": 20,
      "description": "Código (texto)."
     },
     "rate": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Tarifa en % (ICA y ReteICA: por mil)."
     },
     "self_withholding": {
      "type": "boolean"
     }
    },
    "required": [
     "code",
     "rate"
    ]
   },
   "Withholding": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "code": {
      "type": "string",
      "maxLength": 20,
      "description": "Código (texto)."
     },
     "rate": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Tarifa en % (ICA y ReteICA: por mil)."
     },
     "self_withholding": {
      "type": "boolean"
     },
     "base": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     }
    },
    "required": [
     "code",
     "rate"
    ]
   },
   "FreeOfCharge": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "reference_price": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "price_type": {
      "type": "string",
      "maxLength": 20
     }
    }
   },
   "StandardCode": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "scheme": {
      "type": "string",
      "maxLength": 20
     },
     "value": {
      "type": "string"
     }
    }
   },
   "Item": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "code": {
      "type": "string",
      "description": "Código (texto)."
     },
     "description": {
      "type": "string"
     },
     "unit": {
      "type": "string",
      "maxLength": 20,
      "description": "Unidad de medida (tabla 13.3.6). Por defecto 94 (unidad)."
     },
     "quantity": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "unit_price": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Precio unitario SIN impuestos."
     },
     "taxes": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ItemTax"
      },
      "maxItems": 12,
      "description": "Impuestos de la línea: {code, rate} porcentual, {code: \"01\", excluded: true} o nominal {code, unit_amount, unit?, quantity?}."
     },
     "discounts": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ItemAllowance"
      },
      "maxItems": 10
     },
     "charges": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ItemAllowance"
      },
      "maxItems": 10
     },
     "withholdings": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ItemWithholding"
      },
      "maxItems": 10,
      "description": "Retenciones (informativas): 05 ReteIVA, 06 ReteRenta, 07 ReteICA."
     },
     "free_of_charge": {
      "$ref": "#/components/schemas/FreeOfCharge"
     },
     "standard_code": {
      "$ref": "#/components/schemas/StandardCode"
     },
     "brand": {
      "type": "string"
     },
     "model": {
      "type": "string"
     },
     "aiu": {
      "type": "string",
      "maxLength": 20,
      "description": "AIU (solo con `operation_type` \"09\"): \"A\" administración, \"I\" imprevistos, \"U\" utilidad. Solo en facturas."
     },
     "aiu_contract": {
      "type": "string",
      "description": "El objeto del contrato AIU: solo en la línea A, y obligatorio en ella. Solo en facturas."
     },
     "income": {
      "type": "string",
      "enum": [
       "own",
       "third_party"
      ],
      "description": "Mandatos (11): \"own\" (por defecto) o \"third_party\" (con `mandator`). Solo en facturas."
     },
     "mandator": {
      "description": "El mandante de un ingreso para terceros. Solo en facturas.",
      "allOf": [
       {
        "$ref": "#/components/schemas/ItemMandator"
       }
      ]
     },
     "consignment": {
      "description": "La remesa del RNDC (transporte de carga, 12). Solo en facturas.",
      "allOf": [
       {
        "$ref": "#/components/schemas/ItemConsignment"
       }
      ]
     },
     "notary": {
      "description": "Matrícula inmobiliaria y valor comercial (notarios, 14). Solo en facturas.",
      "allOf": [
       {
        "$ref": "#/components/schemas/ItemNotary"
       }
      ]
     },
     "properties": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ItemProperty"
      },
      "maxItems": 20,
      "description": "Propiedades libres de la línea (hasta 20; no en el transporte de carga). Solo en facturas."
     }
    },
    "required": [
     "description",
     "quantity",
     "unit_price"
    ]
   },
   "PaymentMethod": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "code": {
      "type": "string",
      "maxLength": 20,
      "description": "Código (texto)."
     },
     "reference": {
      "type": "string"
     }
    },
    "required": [
     "code"
    ]
   },
   "Payment": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "form": {
      "type": "string",
      "enum": [
       "cash",
       "credit"
      ],
      "description": "cash (contado) | credit (crédito: con due_date o term_days)."
     },
     "term_days": {
      "type": "integer"
     },
     "due_date": {
      "type": "string",
      "format": "date"
     },
     "methods": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/PaymentMethod"
      },
      "maxItems": 5,
      "description": "Medios de pago (tabla 13.3.4.2): 10 efectivo, 42 consignación, 47 transferencia…"
     }
    },
    "required": [
     "form"
    ]
   },
   "Period": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "start": {
      "type": "string",
      "format": "date"
     },
     "end": {
      "type": "string",
      "format": "date"
     }
    }
   },
   "DocumentReference": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "id": {
      "type": "string"
     },
     "date": {
      "type": "string",
      "format": "date"
     }
    }
   },
   "References": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "purchase_order": {
      "$ref": "#/components/schemas/DocumentReference"
     },
     "despatches": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/DocumentReference"
      },
      "maxItems": 20
     },
     "receipts": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/DocumentReference"
      },
      "maxItems": 20
     }
    }
   },
   "AllowanceCharge": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "type": {
      "type": "string",
      "enum": [
       "discount",
       "charge"
      ]
     },
     "code": {
      "type": "string",
      "maxLength": 20,
      "description": "Código (texto)."
     },
     "reason": {
      "type": "string"
     },
     "percent": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "amount": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "base": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     }
    },
    "required": [
     "type"
    ]
   },
   "Prepayment": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "id": {
      "type": "string"
     },
     "amount": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "received_date": {
      "type": "string",
      "format": "date"
     },
     "paid_date": {
      "type": "string",
      "format": "date"
     },
     "instructions": {
      "type": "string"
     }
    },
    "required": [
     "id",
     "amount",
     "received_date"
    ]
   },
   "Currency": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "code": {
      "type": "string",
      "maxLength": 20,
      "description": "Moneda (tabla 13.3.3, ISO 4217), distinta de COP."
     },
     "exchange_rate": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "TRM o tasa pactada: pesos por 1 unidad de la moneda (hasta 6 decimales)."
     },
     "rate_date": {
      "type": "string",
      "format": "date",
      "description": "El día de la tasa; no puede ser posterior a la factura."
     },
     "alternative": {
      "$ref": "#/components/schemas/SupportCurrency"
     }
    },
    "required": [
     "code",
     "exchange_rate",
     "rate_date"
    ]
   },
   "AlternativeCurrency": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "code": {
      "type": "string",
      "maxLength": 20,
      "description": "Una tercera moneda (ni la de la factura ni COP)."
     },
     "exchange_rate": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Unidades de esa moneda por 1 unidad de la moneda de la factura."
     },
     "rate_date": {
      "type": "string",
      "format": "date"
     }
    },
    "required": [
     "code",
     "exchange_rate",
     "rate_date"
    ]
   },
   "DeliveryTerms": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "incoterm": {
      "type": "string",
      "maxLength": 20
     },
     "conditions": {
      "type": "string"
     }
    }
   },
   "ForeignAddress": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "country": {
      "type": "string",
      "maxLength": 20,
      "description": "País (tabla 13.4.1). Sin `country`: Colombia."
     },
     "city": {
      "type": "string",
      "description": "Obligatoria fuera de Colombia."
     },
     "region": {
      "type": "string"
     },
     "region_code": {
      "type": "string",
      "maxLength": 20
     },
     "postal_code": {
      "type": "string",
      "maxLength": 20
     },
     "municipality_code": {
      "type": "string",
      "maxLength": 20,
      "description": "Solo en Colombia (DANE, 5 dígitos)."
     },
     "street": {
      "type": "string",
      "description": "Calle y número."
     }
    }
   },
   "Carrier": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "document_type": {
      "type": "string",
      "maxLength": 20,
      "description": "Tipo de documento del transportador (tabla 13.2.1)."
     },
     "document_number": {
      "type": "string",
      "description": "Sin DV ni puntos; el DV lo calcula Trevol."
     },
     "name": {
      "type": "string"
     },
     "tax_responsibilities": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "maxItems": 20,
      "description": "Tabla 13.2.6.1 (O-13, O-15, O-23, O-47, R-99-PN)."
     },
     "email": {
      "type": "string"
     },
     "phone": {
      "type": "string"
     },
     "address": {
      "$ref": "#/components/schemas/ForeignAddress"
     }
    }
   },
   "Shipment": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "date": {
      "type": "string",
      "format": "date"
     },
     "address": {
      "$ref": "#/components/schemas/ForeignAddress"
     },
     "carrier": {
      "$ref": "#/components/schemas/Carrier"
     }
    }
   },
   "InteroperabilityData": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "name": {
      "type": "string"
     },
     "value": {
      "type": "string"
     }
    },
    "required": [
     "name"
    ]
   },
   "InteroperabilityCollection": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "name": {
      "type": "string"
     },
     "data": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/InteroperabilityData"
      },
      "maxItems": 50
     }
    },
    "required": [
     "name",
     "data"
    ]
   },
   "Interoperability": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "group": {
      "type": "string"
     },
     "collections": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/AirCollection"
      },
      "maxItems": 10
     }
    },
    "required": [
     "group",
     "collections"
    ]
   },
   "ItemMandator": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "document_type": {
      "type": "string",
      "maxLength": 20,
      "description": "Tipo de documento (tabla 13.2.1 de la DIAN): 13 CC, 31 NIT, 22 CE, 41 PA…"
     },
     "document_number": {
      "type": "string",
      "description": "Sin DV ni puntos; el DV lo calcula Trevol."
     },
     "name": {
      "type": "string"
     }
    },
    "required": [
     "document_type",
     "document_number",
     "name"
    ]
   },
   "ItemConsignment": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "rndc_filing": {
      "type": "string",
      "description": "Número de radicación de la remesa en el RNDC (1 a 100 000 millones)."
     },
     "number": {
      "type": "string",
      "description": "Consecutivo interno de la remesa (alfanumérico, hasta 15 caracteres)."
     },
     "freight": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Pesos, sin decimales (la ley los fija en pesos: no se convierte)."
     },
     "quantity": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Cantidad transportada, sin decimales."
     },
     "unit": {
      "type": "string",
      "maxLength": 20,
      "description": "\"KGM\" kilogramos o \"GLL\" galones."
     }
    },
    "required": [
     "rndc_filing",
     "number",
     "freight",
     "quantity",
     "unit"
    ]
   },
   "ItemNotary": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "property_registration": {
      "type": "string"
     },
     "commercial_value": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Pesos: no se convierte."
     }
    },
    "required": [
     "property_registration",
     "commercial_value"
    ]
   },
   "ItemProperty": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "name": {
      "type": "string"
     },
     "value": {
      "type": "string"
     },
     "quantity": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "unit": {
      "type": "string",
      "maxLength": 20,
      "description": "Unidad de medida (tabla 13.3.6); solo con `quantity` (por defecto 94)."
     }
    },
    "required": [
     "name",
     "value"
    ]
   },
   "Seller": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "resident": {
      "type": "boolean",
      "description": "Residente fiscal en Colombia. Por defecto, `country` es CO."
     },
     "person_type": {
      "type": "string",
      "enum": [
       "legal",
       "natural"
      ],
      "description": "Por defecto se deduce del NIT."
     },
     "document_type": {
      "type": "string",
      "maxLength": 20,
      "description": "Residente: solo \"31\" (NIT). No residente: 21, 22, 31, 41, 42, 47 o 50 (tabla 16.2.1)."
     },
     "document_number": {
      "type": "string",
      "description": "Sin dígito de verificación; Trevol calcula el DV del NIT."
     },
     "check_digit": {
      "type": "integer",
      "description": "Opcional: si viene, tiene que ser el DV del NIT."
     },
     "name": {
      "type": "string"
     },
     "address": {
      "type": "string"
     },
     "tax_scheme": {
      "type": "string",
      "maxLength": 20,
      "description": "\"ZZ\" (no aplica, por defecto) o \"01\" (IVA)."
     },
     "tax_responsibilities": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "maxItems": 20,
      "description": "O-13, O-15, O-23, O-47, O-48, O-49 o R-99-PN (por defecto R-99-PN)."
     },
     "country": {
      "type": "string",
      "maxLength": 20,
      "description": "ISO 3166-1 alfa-2 (tabla 16.4.1). Por defecto CO."
     },
     "municipality_code": {
      "type": "string",
      "maxLength": 20,
      "description": "Solo vendedor residente: código DANE del municipio."
     },
     "department_code": {
      "type": "string",
      "maxLength": 20
     },
     "postal_code": {
      "type": "string",
      "maxLength": 20,
      "description": "Residente: de la tabla 16.4.4, del mismo departamento. No residente: libre, hasta 10 caracteres."
     },
     "city": {
      "type": "string",
      "description": "Obligatoria si no es residente."
     },
     "region": {
      "type": "string",
      "description": "Solo vendedor no residente."
     }
    },
    "required": [
     "document_type",
     "document_number",
     "name"
    ]
   },
   "SupportItemTax": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "code": {
      "type": "string",
      "maxLength": 20,
      "description": "Código (texto)."
     },
     "rate": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Tarifa en % (ICA y ReteICA: por mil)."
     },
     "excluded": {
      "type": "boolean"
     }
    },
    "required": [
     "code"
    ]
   },
   "SupportItemCharge": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "reason": {
      "type": "string"
     },
     "percent": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "amount": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     }
    }
   },
   "SupportItemWithholding": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "code": {
      "type": "string",
      "maxLength": 20,
      "description": "Código (texto)."
     },
     "rate": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Tarifa en % (ICA y ReteICA: por mil)."
     }
    },
    "required": [
     "code",
     "rate"
    ]
   },
   "SupportItem": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "code": {
      "type": "string",
      "description": "Código (texto)."
     },
     "description": {
      "type": "string"
     },
     "unit": {
      "type": "string",
      "maxLength": 20,
      "description": "Unidad de medida (tabla 13.3.6). Por defecto 94 (unidad)."
     },
     "quantity": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "unit_price": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Precio unitario SIN impuestos."
     },
     "taxes": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/SupportItemTax"
      },
      "maxItems": 12,
      "description": "Solo IVA: {code: \"01\", rate: 0 | 5 | 19} o {code: \"01\", excluded: true}."
     },
     "discounts": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ItemAllowance"
      },
      "maxItems": 10,
      "description": "Descuentos de la línea, sin código; la razón va de 10 a 5000 caracteres (DSBE04)."
     },
     "charges": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/SupportItemCharge"
      },
      "maxItems": 10
     },
     "withholdings": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/SupportItemWithholding"
      },
      "maxItems": 10,
      "description": "Las practica la empresa al vendedor: 05 ReteIVA (15 o 100 %) o 06 ReteRenta. No restan del total a pagar."
     },
     "standard_code": {
      "$ref": "#/components/schemas/StandardCode"
     },
     "purchase_date": {
      "type": "string",
      "format": "date",
      "description": "Fecha de la compra. Obligatoria en el acumulado semanal (entre 6 días antes de hoy y hoy); por operación no se informa."
     }
    },
    "required": [
     "description",
     "quantity",
     "unit_price"
    ]
   },
   "SupportAdjustmentItem": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "code": {
      "type": "string",
      "description": "Código (texto)."
     },
     "description": {
      "type": "string"
     },
     "unit": {
      "type": "string",
      "maxLength": 20,
      "description": "Unidad de medida (tabla 13.3.6). Por defecto 94 (unidad)."
     },
     "quantity": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "unit_price": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Precio unitario SIN impuestos."
     },
     "taxes": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/SupportItemTax"
      },
      "maxItems": 12,
      "description": "Solo IVA: {code: \"01\", rate: 0 | 5 | 19} o {code: \"01\", excluded: true}."
     },
     "discounts": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ItemAllowance"
      },
      "maxItems": 10,
      "description": "Descuentos de la línea, sin código; la razón va de 10 a 5000 caracteres (NSBE04)."
     },
     "charges": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/SupportItemCharge"
      },
      "maxItems": 10
     },
     "standard_code": {
      "$ref": "#/components/schemas/StandardCode"
     }
    },
    "required": [
     "description",
     "quantity",
     "unit_price"
    ]
   },
   "SupportCurrency": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "code": {
      "type": "string",
      "maxLength": 20,
      "description": "Moneda del documento (ISO 4217); los valores del pedido van en ESA moneda."
     },
     "exchange_rate": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Pesos por 1 unidad de la moneda."
     },
     "rate_date": {
      "type": "string",
      "format": "date"
     }
    },
    "required": [
     "code",
     "exchange_rate",
     "rate_date"
    ]
   },
   "EquivalentItem": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "code": {
      "type": "string",
      "description": "Código (texto)."
     },
     "description": {
      "type": "string"
     },
     "unit": {
      "type": "string",
      "maxLength": 20,
      "description": "Unidad de medida (tabla 13.3.6). Por defecto 94 (unidad)."
     },
     "quantity": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "unit_price": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Precio unitario SIN impuestos."
     },
     "taxes": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ItemTax"
      },
      "maxItems": 12,
      "description": "Impuestos de la línea: {code, rate} porcentual, {code: \"01\", excluded: true} o nominal {code, unit_amount, unit?, quantity?}."
     },
     "discounts": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ItemAllowance"
      },
      "maxItems": 10
     },
     "charges": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ItemAllowance"
      },
      "maxItems": 10
     },
     "withholdings": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ItemWithholding"
      },
      "maxItems": 10,
      "description": "Retenciones (informativas): 05 ReteIVA, 06 ReteRenta, 07 ReteICA."
     },
     "free_of_charge": {
      "$ref": "#/components/schemas/FreeOfCharge"
     },
     "standard_code": {
      "$ref": "#/components/schemas/StandardCode"
     },
     "brand": {
      "type": "string"
     },
     "model": {
      "type": "string"
     },
     "income": {
      "type": "string",
      "enum": [
       "own",
       "collected",
       "third_party"
      ],
      "description": "Mandatos (tabla 16.16): \"own\" (por defecto), \"collected\" (ingreso recaudado para terceros) o \"third_party\" (facturado para terceros); los dos últimos con `mandator`. En 272 y 274 la línea del mandante va con \"collected\"."
     },
     "mandator": {
      "description": "El mandante de un ingreso para terceros (con NIT en 272 y 274).",
      "allOf": [
       {
        "$ref": "#/components/schemas/ItemMandator"
       }
      ]
     }
    },
    "required": [
     "description",
     "quantity",
     "unit_price"
    ]
   },
   "EquivalentAdjustmentItem": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "code": {
      "type": "string",
      "description": "Código (texto)."
     },
     "description": {
      "type": "string"
     },
     "unit": {
      "type": "string",
      "maxLength": 20,
      "description": "Unidad de medida (tabla 13.3.6). Por defecto 94 (unidad)."
     },
     "quantity": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "unit_price": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Precio unitario SIN impuestos."
     },
     "taxes": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ItemTax"
      },
      "maxItems": 12,
      "description": "Impuestos de la línea: {code, rate} porcentual, {code: \"01\", excluded: true} o nominal {code, unit_amount, unit?, quantity?}."
     },
     "discounts": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ItemAllowance"
      },
      "maxItems": 10
     },
     "charges": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ItemAllowance"
      },
      "maxItems": 10
     },
     "free_of_charge": {
      "$ref": "#/components/schemas/FreeOfCharge"
     },
     "standard_code": {
      "$ref": "#/components/schemas/StandardCode"
     },
     "brand": {
      "type": "string"
     },
     "model": {
      "type": "string"
     },
     "income": {
      "type": "string",
      "enum": [
       "own",
       "collected",
       "third_party"
      ],
      "description": "Mandatos (tabla 16.16): \"own\" (por defecto), \"collected\" o \"third_party\"."
     },
     "mandator": {
      "$ref": "#/components/schemas/ItemMandator"
     }
    },
    "required": [
     "description",
     "quantity",
     "unit_price"
    ]
   },
   "PosRegister": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "plate": {
      "type": "string",
      "description": "Placa de inventario de la caja (DEPD26)."
     },
     "location": {
      "type": "string",
      "description": "Ubicación de la caja (DEPD28)."
     },
     "cashier": {
      "type": "string",
      "description": "Nombre del cajero o vendedor (DEPD30)."
     },
     "type": {
      "type": "string",
      "description": "Tipo de caja (DEPD32)."
     },
     "sale_code": {
      "type": "string",
      "description": "Código de la venta. Por defecto, el número del documento (DEPD34)."
     }
    },
    "required": [
     "plate",
     "location",
     "cashier",
     "type"
    ]
   },
   "PosBuyer": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "code": {
      "type": "string",
      "description": "Por defecto, el documento del adquirente."
     },
     "name": {
      "type": "string",
      "description": "Por defecto, el nombre del adquirente."
     },
     "points": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Puntos del comprador. Por defecto, 0."
     }
    }
   },
   "Pos": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "register": {
      "$ref": "#/components/schemas/PosRegister"
     },
     "buyer": {
      "$ref": "#/components/schemas/PosBuyer"
     }
    },
    "required": [
     "register"
    ]
   },
   "OriginNote": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "number": {
      "type": "string"
     },
     "cude": {
      "type": "string",
      "description": "El CUDE de la nota de ajuste (96 hex)."
     },
     "issue_date": {
      "type": "string",
      "format": "date"
     }
    },
    "required": [
     "number",
     "cude",
     "issue_date"
    ]
   },
   "PhysicalDocument": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "number": {
      "type": "string"
     },
     "date": {
      "type": "string",
      "format": "date"
     },
     "type": {
      "type": "string",
      "description": "Codificación propia del tipo del documento físico (hasta 10 caracteres). Por defecto, FISICO."
     }
    }
   },
   "Contingency": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "physical_document": {
      "$ref": "#/components/schemas/PhysicalDocument"
     }
    }
   },
   "Numbering": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "prefix": {
      "type": "string",
      "description": "Prefijo de la resolución POS o de documento soporte que numera (el de `GET /v1/company` → `capabilities.equivalent_documents.pos_numbering` o `capabilities.support_documents.numbering`)."
     }
    },
    "required": [
     "prefix"
    ]
   },
   "CinemaScreening": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "room": {
      "type": "string"
     },
     "seats": {
      "type": "string"
     },
     "screening": {
      "type": "string"
     },
     "location": {
      "type": "string"
     },
     "date": {
      "type": "string",
      "format": "date"
     },
     "time": {
      "type": "string"
     }
    },
    "required": [
     "room",
     "seats",
     "screening"
    ]
   },
   "CinemaExtension": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "address": {
      "type": "string"
     },
     "cinema_room": {
      "type": "string"
     },
     "screenings": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/CinemaScreening"
      },
      "maxItems": 50
     }
    },
    "required": [
     "address",
     "screenings"
    ]
   },
   "ShowProducer": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "name": {
      "type": "string"
     },
     "nit": {
      "type": "string"
     },
     "lep": {
      "type": "string"
     }
    },
    "required": [
     "name",
     "nit"
    ]
   },
   "ShowEvent": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "name": {
      "type": "string"
     },
     "locality": {
      "type": "string"
     },
     "pulep": {
      "type": "string"
     },
     "sale_type": {
      "type": "string"
     },
     "sale_phase": {
      "type": "string"
     },
     "category": {
      "type": "string"
     },
     "municipality_code": {
      "type": "string",
      "maxLength": 20,
      "description": "Código DANE del municipio (5 dígitos)."
     },
     "venue": {
      "type": "string"
     },
     "date": {
      "type": "string",
      "format": "date"
     },
     "time": {
      "type": "string"
     }
    },
    "required": [
     "name",
     "locality"
    ]
   },
   "ShowExtension": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "producer": {
      "$ref": "#/components/schemas/ShowProducer"
     },
     "event": {
      "$ref": "#/components/schemas/ShowEvent"
     }
    },
    "required": [
     "producer",
     "event"
    ]
   },
   "GamesVenue": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "address": {
      "type": "string"
     },
     "deposit": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     }
    },
    "required": [
     "address",
     "deposit"
    ]
   },
   "Game": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "type": {
      "type": "string"
     },
     "total": {
      "type": "integer"
     }
    },
    "required": [
     "type",
     "total"
    ]
   },
   "GameCredit": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "serial": {
      "type": "string"
     },
     "amount": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     }
    },
    "required": [
     "serial",
     "amount"
    ]
   },
   "GamesExtension": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "venue": {
      "$ref": "#/components/schemas/GamesVenue"
     },
     "games": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Game"
      },
      "maxItems": 2
     },
     "credits": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/GameCredit"
      },
      "maxItems": 500
     }
    },
    "required": [
     "venue",
     "games"
    ]
   },
   "TransportExtension": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "mode": {
      "type": "string"
     },
     "vehicle_id": {
      "type": "string"
     },
     "vehicle": {
      "type": "string"
     },
     "origin": {
      "type": "string"
     },
     "destination": {
      "type": "string"
     }
    },
    "required": [
     "mode",
     "vehicle_id",
     "vehicle",
     "origin",
     "destination"
    ]
   },
   "AirCollection": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "name": {
      "type": "string"
     },
     "data": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/InteroperabilityData"
      },
      "maxItems": 50
     }
    },
    "required": [
     "name",
     "data"
    ]
   },
   "AirExtension": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "group": {
      "type": "string"
     },
     "collections": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/AirCollection"
      },
      "maxItems": 50
     },
     "passengers": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/AirCollection"
      },
      "maxItems": 50
     }
    },
    "required": [
     "collections",
     "passengers"
    ]
   },
   "StockExchangePrices": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "registration": {
      "type": "string"
     },
     "total_assignment": {
      "type": "string"
     }
    }
   },
   "StockExchangeExtension": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "trade_number": {
      "type": "string"
     },
     "settlement_date": {
      "type": "string",
      "format": "date"
     },
     "nominal_quantity": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "prices": {
      "$ref": "#/components/schemas/StockExchangePrices"
     },
     "yields": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "value": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "commission_percent": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     }
    },
    "required": [
     "trade_number",
     "settlement_date",
     "nominal_quantity",
     "prices",
     "value",
     "commission_percent"
    ]
   },
   "ConsumptionAdjustment": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "reason": {
      "type": "string"
     },
     "amount": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     }
    },
    "required": [
     "reason",
     "amount"
    ]
   },
   "Meter": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "number": {
      "type": "string"
     },
     "previous_date": {
      "type": "string",
      "format": "date"
     },
     "previous_reading": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "current_date": {
      "type": "string",
      "format": "date"
     },
     "current_reading": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "method": {
      "type": "string"
     },
     "days": {
      "type": "integer"
     }
    },
    "required": [
     "number"
    ]
   },
   "Consumption": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "unit": {
      "type": "string",
      "maxLength": 20,
      "description": "Unidad de medida (tabla 13.3.6). Por defecto 94 (unidad)."
     },
     "quantity": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "subtotal": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "discounts": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ConsumptionAdjustment"
      },
      "maxItems": 50
     },
     "charges": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ConsumptionAdjustment"
      },
      "maxItems": 50
     },
     "meter": {
      "$ref": "#/components/schemas/Meter"
     }
    },
    "required": [
     "quantity",
     "subtotal"
    ]
   },
   "ThirdPartyCompany": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "nit": {
      "type": "string"
     },
     "name": {
      "type": "string"
     }
    },
    "required": [
     "nit",
     "name"
    ]
   },
   "ThirdPartyCharge": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "service": {
      "type": "string"
     },
     "company": {
      "$ref": "#/components/schemas/ThirdPartyCompany"
     },
     "reason": {
      "type": "string"
     },
     "contract": {
      "type": "string"
     },
     "period": {
      "type": "string"
     },
     "note": {
      "type": "string"
     },
     "total": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "charges": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ConsumptionAdjustment"
      },
      "maxItems": 50
     }
    },
    "required": [
     "service",
     "company",
     "total"
    ]
   },
   "PublicServicesExtension": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "service": {
      "type": "string"
     },
     "company": {
      "type": "string"
     },
     "reason": {
      "type": "string"
     },
     "contract": {
      "type": "string"
     },
     "use": {
      "type": "string",
      "maxLength": 20
     },
     "stratum": {
      "type": "string",
      "maxLength": 20
     },
     "payment_due_date": {
      "type": "string",
      "format": "date"
     },
     "payment_reference": {
      "type": "string"
     },
     "due_date": {
      "type": "string",
      "format": "date"
     },
     "period": {
      "type": "string",
      "format": "date"
     },
     "cycle_days": {
      "type": "integer"
     },
     "notes": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "maxItems": 10
     },
     "consumptions": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Consumption"
      },
      "maxItems": 50
     },
     "third_parties": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ThirdPartyCharge"
      },
      "maxItems": 20
     }
    },
    "required": [
     "service",
     "company",
     "contract",
     "use",
     "stratum",
     "consumptions"
    ]
   },
   "PayrollPlace": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "country": {
      "type": "string",
      "maxLength": 20
     },
     "department_code": {
      "type": "string",
      "maxLength": 20
     },
     "municipality_code": {
      "type": "string",
      "maxLength": 20,
      "description": "Código DANE del municipio (5 dígitos)."
     }
    }
   },
   "PayrollWorkplace": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "country": {
      "type": "string",
      "maxLength": 20
     },
     "department_code": {
      "type": "string",
      "maxLength": 20
     },
     "municipality_code": {
      "type": "string",
      "maxLength": 20,
      "description": "Código DANE del municipio (5 dígitos)."
     },
     "address": {
      "type": "string"
     }
    }
   },
   "PayrollPeriod": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "hire_date": {
      "type": "string",
      "format": "date"
     },
     "start": {
      "type": "string",
      "format": "date"
     },
     "end": {
      "type": "string",
      "format": "date"
     },
     "termination_date": {
      "type": "string",
      "format": "date"
     },
     "time_worked": {
      "type": "integer"
     }
    },
    "required": [
     "hire_date",
     "start",
     "end"
    ]
   },
   "PayrollNovelty": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "cune": {
      "type": "string"
     }
    },
    "required": [
     "cune"
    ]
   },
   "PayrollPayment": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "form": {
      "type": "string",
      "maxLength": 20,
      "description": "Forma de pago (tabla 5.3.3.1); por defecto \"1\" (contado)."
     },
     "method": {
      "type": "string",
      "maxLength": 20,
      "description": "Medio de pago (tabla 5.3.3.2)."
     },
     "bank": {
      "type": "string"
     },
     "account_type": {
      "type": "string"
     },
     "account_number": {
      "type": "string"
     }
    },
    "required": [
     "method"
    ]
   },
   "PayrollEmployee": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "type": {
      "type": "string",
      "maxLength": 20,
      "description": "Tipo de trabajador (tabla 5.5.3)."
     },
     "subtype": {
      "type": "string",
      "maxLength": 20
     },
     "high_risk_pension": {
      "type": "boolean"
     },
     "document_type": {
      "type": "string",
      "maxLength": 20,
      "description": "Tipo de documento del trabajador (tabla 5.2.1)."
     },
     "document_number": {
      "type": "string",
      "description": "Solo dígitos, sin puntos ni comas ni espacios."
     },
     "first_surname": {
      "type": "string"
     },
     "second_surname": {
      "type": "string",
      "description": "Obligatorio (NIE047): la DIAN lo exige aunque la base no."
     },
     "first_name": {
      "type": "string"
     },
     "other_names": {
      "type": "string"
     },
     "workplace": {
      "$ref": "#/components/schemas/PayrollWorkplace"
     },
     "integral_salary": {
      "type": "boolean"
     },
     "contract_type": {
      "type": "string",
      "maxLength": 20,
      "description": "Tipo de contrato (tabla 5.5.2)."
     },
     "salary": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "code": {
      "type": "string",
      "description": "El código interno del empleado (filtra las listas con `employee_code`; no es un dato de identificación)."
     }
    },
    "required": [
     "type",
     "document_type",
     "document_number",
     "first_surname",
     "second_surname",
     "first_name",
     "workplace",
     "contract_type",
     "salary"
    ]
   },
   "PayrollEmployer": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "first_surname": {
      "type": "string"
     },
     "second_surname": {
      "type": "string"
     },
     "first_name": {
      "type": "string"
     },
     "other_names": {
      "type": "string"
     }
    },
    "required": [
     "first_surname",
     "second_surname",
     "first_name"
    ]
   },
   "PayrollBasic": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "days": {
      "type": "integer"
     },
     "amount": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     }
    },
    "required": [
     "days",
     "amount"
    ]
   },
   "PayrollTransport": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "allowance": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "salary_per_diem": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "non_salary_per_diem": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     }
    }
   },
   "PayrollOvertime": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "type": {
      "type": "string",
      "maxLength": 20,
      "description": "Tabla 5.5.5: HED, HEN, HRN, HEDDF, HRDDF, HENDF, HRNDF. El porcentaje sale de la tabla."
     },
     "quantity": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "amount": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "start": {
      "type": "string",
      "description": "AAAA-MM-DDTHH:MM:SS (NIE074)."
     },
     "end": {
      "type": "string",
      "description": "AAAA-MM-DDTHH:MM:SS (NIE074)."
     },
     "percent": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     }
    },
    "required": [
     "type",
     "quantity",
     "amount"
    ]
   },
   "PayrollPaidPeriod": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "start": {
      "type": "string",
      "format": "date"
     },
     "end": {
      "type": "string",
      "format": "date"
     },
     "days": {
      "type": "integer"
     },
     "amount": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     }
    },
    "required": [
     "days",
     "amount"
    ]
   },
   "PayrollCompensatedVacation": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "days": {
      "type": "integer"
     },
     "amount": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     }
    },
    "required": [
     "days",
     "amount"
    ]
   },
   "PayrollVacation": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "regular": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/PayrollPaidPeriod"
      },
      "maxItems": 100
     },
     "compensated": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/PayrollCompensatedVacation"
      },
      "maxItems": 100
     }
    }
   },
   "PayrollServiceBonus": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "days": {
      "type": "integer"
     },
     "amount": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "non_salary_amount": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     }
    },
    "required": [
     "days",
     "amount"
    ]
   },
   "PayrollSeverance": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "amount": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "percent": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "interest": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     }
    },
    "required": [
     "amount",
     "percent",
     "interest"
    ]
   },
   "PayrollDisability": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "start": {
      "type": "string",
      "format": "date"
     },
     "end": {
      "type": "string",
      "format": "date"
     },
     "days": {
      "type": "integer"
     },
     "type": {
      "type": "string",
      "maxLength": 20,
      "description": "Tabla 5.5.6: \"1\" común, \"2\" profesional, \"3\" laboral."
     },
     "amount": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     }
    },
    "required": [
     "days",
     "type",
     "amount"
    ]
   },
   "PayrollUnpaidPeriod": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "start": {
      "type": "string",
      "format": "date"
     },
     "end": {
      "type": "string",
      "format": "date"
     },
     "days": {
      "type": "integer"
     }
    },
    "required": [
     "days"
    ]
   },
   "PayrollLeaves": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "maternity_paternity": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/PayrollPaidPeriod"
      },
      "maxItems": 100
     },
     "paid": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/PayrollPaidPeriod"
      },
      "maxItems": 100
     },
     "unpaid": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/PayrollUnpaidPeriod"
      },
      "maxItems": 100
     }
    }
   },
   "PayrollSalaryAmounts": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "salary": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "non_salary": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     }
    }
   },
   "PayrollOtherConcept": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "description": {
      "type": "string"
     },
     "salary": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "non_salary": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     }
    },
    "required": [
     "description"
    ]
   },
   "PayrollCompensation": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "ordinary": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "extraordinary": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     }
    },
    "required": [
     "ordinary",
     "extraordinary"
    ]
   },
   "PayrollEpctvBonus": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "salary_payment": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "non_salary_payment": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "food_salary": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "food_non_salary": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     }
    }
   },
   "PayrollEarnings": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "basic": {
      "description": "El sueldo básico (obligatorio).",
      "allOf": [
       {
        "$ref": "#/components/schemas/PayrollBasic"
       }
      ]
     },
     "transport": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/PayrollTransport"
      },
      "maxItems": 100
     },
     "overtime": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/PayrollOvertime"
      },
      "maxItems": 500
     },
     "vacation": {
      "$ref": "#/components/schemas/PayrollVacation"
     },
     "service_bonus": {
      "$ref": "#/components/schemas/PayrollServiceBonus"
     },
     "severance": {
      "$ref": "#/components/schemas/PayrollSeverance"
     },
     "disabilities": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/PayrollDisability"
      },
      "maxItems": 100
     },
     "leaves": {
      "$ref": "#/components/schemas/PayrollLeaves"
     },
     "bonuses": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/PayrollSalaryAmounts"
      },
      "maxItems": 100
     },
     "allowances": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/PayrollSalaryAmounts"
      },
      "maxItems": 100
     },
     "strikes": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/PayrollUnpaidPeriod"
      },
      "maxItems": 100
     },
     "other_concepts": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/PayrollOtherConcept"
      },
      "maxItems": 100
     },
     "compensations": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/PayrollCompensation"
      },
      "maxItems": 100
     },
     "epctv_bonuses": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/PayrollEpctvBonus"
      },
      "maxItems": 100
     },
     "commissions": {
      "type": "array",
      "items": {
       "oneOf": [
        {
         "type": "string",
         "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
        },
        {
         "type": "number"
        }
       ],
       "description": "Número o texto decimal con punto («150000.50»)."
      },
      "maxItems": 100
     },
     "third_party_payments": {
      "type": "array",
      "items": {
       "oneOf": [
        {
         "type": "string",
         "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
        },
        {
         "type": "number"
        }
       ],
       "description": "Número o texto decimal con punto («150000.50»)."
      },
      "maxItems": 100
     },
     "advances": {
      "type": "array",
      "items": {
       "oneOf": [
        {
         "type": "string",
         "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
        },
        {
         "type": "number"
        }
       ],
       "description": "Número o texto decimal con punto («150000.50»)."
      },
      "maxItems": 100
     },
     "endowment": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "sustenance_support": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "telework": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "retirement_bonus": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "indemnity": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "refund": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     }
    },
    "required": [
     "basic"
    ]
   },
   "PayrollPercentAmount": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "percent": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "amount": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     }
    },
    "required": [
     "percent",
     "amount"
    ]
   },
   "PayrollSolidarityFund": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "percent": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "amount": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "subsistence_percent": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "subsistence_amount": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     }
    }
   },
   "PayrollSanction": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "public": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "private": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     }
    },
    "required": [
     "public",
     "private"
    ]
   },
   "PayrollLoan": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "description": {
      "type": "string"
     },
     "amount": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     }
    },
    "required": [
     "description",
     "amount"
    ]
   },
   "PayrollDeductions": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "health": {
      "description": "Salud (obligatoria).",
      "allOf": [
       {
        "$ref": "#/components/schemas/PayrollPercentAmount"
       }
      ]
     },
     "pension": {
      "description": "Pensión (obligatoria).",
      "allOf": [
       {
        "$ref": "#/components/schemas/PayrollPercentAmount"
       }
      ]
     },
     "solidarity_fund": {
      "$ref": "#/components/schemas/PayrollSolidarityFund"
     },
     "unions": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/PayrollPercentAmount"
      },
      "maxItems": 100
     },
     "sanctions": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/PayrollSanction"
      },
      "maxItems": 100
     },
     "payroll_loans": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/PayrollLoan"
      },
      "maxItems": 100
     },
     "third_party_payments": {
      "type": "array",
      "items": {
       "oneOf": [
        {
         "type": "string",
         "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
        },
        {
         "type": "number"
        }
       ],
       "description": "Número o texto decimal con punto («150000.50»)."
      },
      "maxItems": 100
     },
     "advances": {
      "type": "array",
      "items": {
       "oneOf": [
        {
         "type": "string",
         "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
        },
        {
         "type": "number"
        }
       ],
       "description": "Número o texto decimal con punto («150000.50»)."
      },
      "maxItems": 100
     },
     "other": {
      "type": "array",
      "items": {
       "oneOf": [
        {
         "type": "string",
         "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
        },
        {
         "type": "number"
        }
       ],
       "description": "Número o texto decimal con punto («150000.50»)."
      },
      "maxItems": 100
     },
     "voluntary_pension": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "withholding_tax": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "afc": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "cooperative": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "tax_garnishment": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "complementary_plan": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "education": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "refund": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "debt": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     }
    },
    "required": [
     "health",
     "pension"
    ]
   },
   "ReceivedInvoiceIssuer": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "nit": {
      "type": "string"
     },
     "check_digit": {
      "type": "integer",
      "description": "Opcional: si viene, tiene que ser el DV del NIT."
     },
     "document_type": {
      "type": "string",
      "maxLength": 20,
      "description": "Tipo de documento (tabla 13.2.1 de la DIAN): 13 CC, 31 NIT, 22 CE, 41 PA…"
     },
     "name": {
      "type": "string",
      "description": "Se guarda (va en el XML) pero no sale en los webhooks."
     }
    }
   },
   "ReceivedInvoice": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "cufe": {
      "type": "string",
      "description": "El CUFE de la factura (96 caracteres hexadecimales)."
     },
     "number": {
      "type": "string",
      "description": "El número de la factura, con su prefijo. En el 034 es opcional: si viene, tiene que ser el de la factura de ese CUFE."
     },
     "type": {
      "type": "string",
      "maxLength": 20,
      "description": "Tipo de documento de la factura (\"01\" a \"04\"; por defecto \"01\"). No va en el 034."
     },
     "issuer": {
      "$ref": "#/components/schemas/ReceivedInvoiceIssuer"
     },
     "acquirer_document_type": {
      "type": "string",
      "maxLength": 20,
      "description": "El tipo de documento con que el emisor identificó a la empresa en la factura (\"31\" NIT o \"13\" cédula). Por defecto, el de la empresa (si no, la regla AAH09)."
     }
    }
   },
   "EventClaim": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "code": {
      "type": "string",
      "maxLength": 20,
      "description": "Código (texto)."
     },
     "note": {
      "type": "string"
     }
    }
   },
   "InvoiceReference": {
    "oneOf": [
     {
      "type": "object",
      "additionalProperties": false,
      "required": [
       "id"
      ],
      "properties": {
       "id": {
        "type": "string",
        "pattern": "^inv_[0-9a-f]{32}$"
       }
      }
     },
     {
      "type": "object",
      "additionalProperties": false,
      "required": [
       "number",
       "cufe",
       "issue_date"
      ],
      "properties": {
       "number": {
        "type": "string"
       },
       "cufe": {
        "type": "string",
        "pattern": "^[0-9a-fA-F]{96}$"
       },
       "issue_date": {
        "type": "string",
        "format": "date"
       },
       "total": {
        "oneOf": [
         {
          "type": "string",
          "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
         },
         {
          "type": "number"
         }
        ],
        "description": "Número o texto decimal con punto («150000.50»)."
       }
      }
     }
    ]
   },
   "InvoiceInput": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "external_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9:._/-]{1,100}$",
      "description": "Tu identificador del documento: único entre los documentos API de la empresa y el ambiente."
     },
     "customer": {
      "$ref": "#/components/schemas/Customer"
     },
     "items": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Item"
      },
      "maxItems": 500,
      "description": "Las líneas (1 a 500)."
     },
     "payment": {
      "$ref": "#/components/schemas/Payment"
     },
     "notes": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "maxItems": 10
     },
     "period": {
      "$ref": "#/components/schemas/Period"
     },
     "references": {
      "$ref": "#/components/schemas/References"
     },
     "allowance_charges": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/AllowanceCharge"
      },
      "maxItems": 20,
      "description": "Descuentos y recargos globales (no tocan las bases)."
     },
     "prepayments": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Prepayment"
      },
      "maxItems": 20,
      "description": "Anticipos (informativos: no restan del total)."
     },
     "withholdings": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Withholding"
      },
      "maxItems": 10,
      "description": "Retenciones (informativas): 05 ReteIVA, 06 ReteRenta, 07 ReteICA."
     },
     "rounding": {
      "oneOf": [
       {
        "type": "boolean"
       },
       {
        "oneOf": [
         {
          "type": "string",
          "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
         },
         {
          "type": "number"
         }
        ],
        "description": "Número o texto decimal con punto («150000.50»)."
       }
      ],
      "description": "true = redondeo al peso; o un valor entre -2.00 y 2.00."
     },
     "document_type": {
      "type": "string",
      "maxLength": 20,
      "description": "Tipo de factura (tabla 13.1.3): \"01\" venta (por defecto) o \"02\" exportación. La contingencia (03/04) todavía no está disponible en la API."
     },
     "operation_type": {
      "type": "string",
      "maxLength": 20,
      "description": "Tipo de operación (tabla 13.1.5.1): \"10\" estándar (por defecto), \"09\" AIU, \"11\" mandatos, \"12\" transporte de carga, \"14\" notarios, \"15\" compra o \"16\" venta de divisas, o \"SS-CUFE\" (sector salud, con `interoperability`)."
     },
     "currency": {
      "description": "Moneda extranjera: los valores del pedido van en ESA moneda; la factura y el CUFE van en pesos (× la tasa). Sin `currency`, la factura es en pesos.",
      "allOf": [
       {
        "$ref": "#/components/schemas/Currency"
       }
      ]
     },
     "cop_totals": {
      "type": "boolean",
      "description": "Con `currency`: informa la moneda y la tasa en la interoperabilidad («Exportación» / «Factura de Venta»)."
     },
     "delivery_terms": {
      "description": "Condiciones de entrega de la exportación (tabla 13.3.7: INCOTERM).",
      "allOf": [
       {
        "$ref": "#/components/schemas/DeliveryTerms"
       }
      ]
     },
     "shipment": {
      "description": "El envío físico de la mercancía (fecha, dirección y transportador). No se llama `delivery`: esa clave de la respuesta es el estado de los archivos y del correo.",
      "allOf": [
       {
        "$ref": "#/components/schemas/Shipment"
       }
      ]
     },
     "due_diligence": {
      "type": "string",
      "maxLength": 20,
      "description": "Debida diligencia (tabla 18.3: \"01\"–\"04\"). Obligatoria en la compra y venta de divisas (15/16) y prohibida en los demás tipos de operación."
     },
     "interoperability": {
      "description": "Grupo de interoperabilidad (Suplemento H). Obligatorio con `operation_type` \"SS-CUFE\".",
      "allOf": [
       {
        "$ref": "#/components/schemas/Interoperability"
       }
      ]
     }
    },
    "required": [
     "items"
    ]
   },
   "NoteInput": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "external_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9:._/-]{1,100}$",
      "description": "Tu identificador del documento: único entre los documentos API de la empresa y el ambiente."
     },
     "customer": {
      "$ref": "#/components/schemas/Customer"
     },
     "items": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Item"
      },
      "maxItems": 500,
      "description": "Las líneas (1 a 500)."
     },
     "payment": {
      "$ref": "#/components/schemas/Payment"
     },
     "notes": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "maxItems": 10
     },
     "period": {
      "$ref": "#/components/schemas/Period"
     },
     "references": {
      "$ref": "#/components/schemas/References"
     },
     "allowance_charges": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/AllowanceCharge"
      },
      "maxItems": 20,
      "description": "Descuentos y recargos globales (no tocan las bases)."
     },
     "prepayments": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Prepayment"
      },
      "maxItems": 20,
      "description": "Anticipos (informativos: no restan del total)."
     },
     "withholdings": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Withholding"
      },
      "maxItems": 10,
      "description": "Retenciones (informativas): 05 ReteIVA, 06 ReteRenta, 07 ReteICA."
     },
     "rounding": {
      "oneOf": [
       {
        "type": "boolean"
       },
       {
        "oneOf": [
         {
          "type": "string",
          "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
         },
         {
          "type": "number"
         }
        ],
        "description": "Número o texto decimal con punto («150000.50»)."
       }
      ],
      "description": "true = redondeo al peso; o un valor entre -2.00 y 2.00."
     },
     "concept": {
      "type": "string",
      "maxLength": 20,
      "description": "Concepto de corrección: NC 1–6, ND 1–4."
     },
     "description": {
      "type": "string"
     },
     "invoice": {
      "$ref": "#/components/schemas/InvoiceReference"
     }
    },
    "required": [
     "items",
     "concept"
    ]
   },
   "SupportDocumentInput": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "external_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9:._/-]{1,100}$",
      "description": "Tu identificador del documento: único entre los documentos API de la empresa y el ambiente."
     },
     "seller": {
      "description": "Quien vende y no está obligado a facturar (el SNO). La empresa de la llave es la compradora: sus datos salen de la empresa. No hay `customer`.",
      "allOf": [
       {
        "$ref": "#/components/schemas/Seller"
       }
      ]
     },
     "items": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/SupportItem"
      },
      "maxItems": 500,
      "description": "Las líneas (1 a 500). Retenciones solo por línea (`withholdings`: 05 ReteIVA, 06 ReteRenta); las del documento no se publican."
     },
     "payment": {
      "$ref": "#/components/schemas/Payment"
     },
     "notes": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "maxItems": 10
     },
     "references": {
      "$ref": "#/components/schemas/References"
     },
     "allowance_charges": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/AllowanceCharge"
      },
      "maxItems": 20,
      "description": "Descuentos y recargos globales (no tocan las bases)."
     },
     "currency": {
      "$ref": "#/components/schemas/SupportCurrency"
     },
     "transmission": {
      "type": "string",
      "enum": [
       "per_operation",
       "weekly"
      ],
      "description": "`per_operation` (por defecto, un documento por compra) o `weekly` (acumulado semanal con un mismo vendedor: cada línea lleva su `purchase_date`)."
     },
     "adjustment_note": {
      "description": "La nota de ajuste que originó este documento (opcional): {\"id\": \"sda_…\"} o {number, cuds, issue_date}.",
      "allOf": [
       {
        "$ref": "#/components/schemas/SupportAdjustmentReference"
       }
      ]
     },
     "numbering": {
      "description": "Opcional: el prefijo de la resolución de documento soporte que numera (una empresa con varios rangos). Sin él, la más nueva vigente. Si no existe, `numbering_unavailable` (`no_resolution`).",
      "allOf": [
       {
        "$ref": "#/components/schemas/Numbering"
       }
      ]
     }
    },
    "required": [
     "items",
     "seller"
    ]
   },
   "SupportDocumentAdjustmentInput": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "external_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9:._/-]{1,100}$",
      "description": "Tu identificador del documento: único entre los documentos API de la empresa y el ambiente."
     },
     "seller": {
      "description": "Opcional con `support_document.id`: se toma el vendedor del documento soporte (si viene, tiene que ser el mismo).",
      "allOf": [
       {
        "$ref": "#/components/schemas/Seller"
       }
      ]
     },
     "items": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/SupportAdjustmentItem"
      },
      "maxItems": 500,
      "description": "Las líneas de la nota (1 a 500): sin retenciones ni fecha de compra."
     },
     "payment": {
      "$ref": "#/components/schemas/Payment"
     },
     "notes": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "maxItems": 10
     },
     "references": {
      "$ref": "#/components/schemas/References"
     },
     "allowance_charges": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/AllowanceCharge"
      },
      "maxItems": 20,
      "description": "Descuentos y recargos globales (no tocan las bases)."
     },
     "currency": {
      "$ref": "#/components/schemas/SupportCurrency"
     },
     "concept": {
      "type": "string",
      "maxLength": 20,
      "description": "Concepto de la nota de ajuste (tabla 16.2.4): \"1\" devolución parcial, \"2\" anulación del documento soporte (lleva exactamente sus valores), \"3\" rebaja o descuento, \"4\" ajuste de precio, \"5\" otros."
     },
     "description": {
      "type": "string",
      "description": "Qué se corrige y por qué (de 20 a 5000 caracteres, NSBF04)."
     },
     "support_document": {
      "description": "El documento soporte que ajusta: {\"id\": \"sd_…\"} (de Trevol: validado, de la empresa y el ambiente de la llave) o {number, cuds, issue_date, total?} si es de otra plataforma (`total` hace falta para anularlo).",
      "allOf": [
       {
        "$ref": "#/components/schemas/SupportDocumentReference"
       }
      ]
     }
    },
    "required": [
     "items",
     "concept",
     "description",
     "support_document"
    ]
   },
   "EquivalentDocumentInput": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "external_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9:._/-]{1,100}$",
      "description": "Tu identificador del documento: único entre los documentos API de la empresa y el ambiente."
     },
     "customer": {
      "description": "El adquirente. Para consumidor final: {\"final_consumer\": true}. La relación de juegos (30) no lleva `customer`: el adquirente es la DIAN.",
      "allOf": [
       {
        "$ref": "#/components/schemas/Customer"
       }
      ]
     },
     "items": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/EquivalentItem"
      },
      "maxItems": 500,
      "description": "Las líneas (1 a 500). Retenciones solo como autorretenciones del emisor (`self_withholding: true`)."
     },
     "payment": {
      "$ref": "#/components/schemas/Payment"
     },
     "notes": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "maxItems": 10
     },
     "period": {
      "$ref": "#/components/schemas/Period"
     },
     "references": {
      "$ref": "#/components/schemas/References"
     },
     "allowance_charges": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/AllowanceCharge"
      },
      "maxItems": 20,
      "description": "Descuentos y recargos globales (no tocan las bases)."
     },
     "prepayments": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Prepayment"
      },
      "maxItems": 20,
      "description": "Anticipos (informativos: no restan del total)."
     },
     "withholdings": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Withholding"
      },
      "maxItems": 10,
      "description": "Retenciones (informativas): 05 ReteIVA, 06 ReteRenta, 07 ReteICA."
     },
     "rounding": {
      "oneOf": [
       {
        "type": "boolean"
       },
       {
        "oneOf": [
         {
          "type": "string",
          "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
         },
         {
          "type": "number"
         }
        ],
        "description": "Número o texto decimal con punto («150000.50»)."
       }
      ],
      "description": "true = redondeo al peso; o un valor entre -2.00 y 2.00."
     },
     "document_type": {
      "type": "string",
      "maxLength": 20,
      "description": "Tipo de documento equivalente (tabla 16.3): \"20\" tiquete POS (por defecto), \"25\" boleta de cine, \"27\" espectáculos públicos, \"30\" juegos localizados y no localizados (se acepta \"32\"), \"35\" transporte de pasajeros, \"40\" peajes, \"45\" extracto, \"50\" tiquete aéreo, \"55\" bolsa de valores o \"60\" servicios públicos."
     },
     "operation_type": {
      "type": "string",
      "maxLength": 20,
      "description": "Tipo de operación (CustomizationID, tabla 16.4.1) del tipo de documento. Por defecto, el primero del tipo (\"10\" en el POS)."
     },
     "pos": {
      "description": "Obligatorio en el tiquete POS (20) y prohibido en los demás: la caja que expide el tiquete y, opcional, los beneficios del comprador.",
      "allOf": [
       {
        "$ref": "#/components/schemas/Pos"
       }
      ]
     },
     "extension": {
      "description": "La información propia del tipo, con UNA clave, la de su `document_type`: `cinema` (25), `show` (27), `games` (30), `transport` (35), `air` (50), `stock_exchange` (55) o `public_services` (60). Prohibida en el POS (20), peajes (40) y extracto (45).",
      "allOf": [
       {
        "$ref": "#/components/schemas/Extension"
       }
      ]
     },
     "prefix": {
      "type": "string",
      "description": "Solo en los tipos sin resolución (todos menos el POS): el prefijo del consecutivo propio (1 a 4 letras o dígitos). Por defecto, el del tipo (DEC, DEEP, DEJL, DETT, DEP, EXT, DETA, DEBV, SPD)."
     },
     "origin_note": {
      "description": "La nota de ajuste que dio origen a este documento (opcional).",
      "allOf": [
       {
        "$ref": "#/components/schemas/OriginNote"
       }
      ]
     },
     "contingency": {
      "description": "Solo la contingencia 07 (el emisor transcribe un documento físico): `physical_document` con number, date y type. La 08 (la DIAN no contestó) no se pide: la decide Trevol y el documento responde `202` con `status: contingency`.",
      "allOf": [
       {
        "$ref": "#/components/schemas/Contingency"
       }
      ]
     },
     "numbering": {
      "description": "Solo en el POS: el prefijo de la resolución POS que numera (una empresa con varias cajas o establecimientos tiene varias). Sin él, la más nueva vigente. Si no existe, `numbering_unavailable` (`no_resolution`).",
      "allOf": [
       {
        "$ref": "#/components/schemas/Numbering"
       }
      ]
     }
    },
    "required": [
     "items"
    ]
   },
   "EquivalentDocumentAdjustmentInput": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "external_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9:._/-]{1,100}$",
      "description": "Tu identificador del documento: único entre los documentos API de la empresa y el ambiente."
     },
     "customer": {
      "description": "Opcional con `equivalent_document.id`: se toma el adquirente del documento (si viene, tiene que ser el mismo).",
      "allOf": [
       {
        "$ref": "#/components/schemas/Customer"
       }
      ]
     },
     "items": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/EquivalentAdjustmentItem"
      },
      "maxItems": 500,
      "description": "Las líneas (1 a 500)."
     },
     "payment": {
      "$ref": "#/components/schemas/Payment"
     },
     "notes": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "maxItems": 10
     },
     "period": {
      "$ref": "#/components/schemas/Period"
     },
     "references": {
      "$ref": "#/components/schemas/References"
     },
     "allowance_charges": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/AllowanceCharge"
      },
      "maxItems": 20,
      "description": "Descuentos y recargos globales (no tocan las bases)."
     },
     "prepayments": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Prepayment"
      },
      "maxItems": 20,
      "description": "Anticipos (informativos: no restan del total)."
     },
     "rounding": {
      "oneOf": [
       {
        "type": "boolean"
       },
       {
        "oneOf": [
         {
          "type": "string",
          "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
         },
         {
          "type": "number"
         }
        ],
        "description": "Número o texto decimal con punto («150000.50»)."
       }
      ],
      "description": "true = redondeo al peso; o un valor entre -2.00 y 2.00."
     },
     "note_type": {
      "type": "string",
      "enum": [
       "credit",
       "debit"
      ],
      "description": "\"credit\" (nota de ajuste crédito, 94) o \"debit\" (débito, 93)."
     },
     "concept": {
      "type": "string",
      "maxLength": 20,
      "description": "Concepto de la nota (tabla 16.6): \"1\" devolución parcial, \"2\" anulación del documento (lleva exactamente sus valores), \"3\" rebaja o descuento, \"4\" ajuste de precio, \"5\" otros."
     },
     "description": {
      "type": "string",
      "description": "Opcional (20 a 5000 caracteres). Sin ella, Trevol pone el texto de la tabla (el EXACTO en la nota débito: NADBF04)."
     },
     "equivalent_document": {
      "description": "El documento que ajusta: {\"id\": \"pos_…\"} (de Trevol: validado, de la empresa y el ambiente de la llave) o {number, cude, issue_date, document_type, total?} si es de otra plataforma (`total` hace falta para anularlo).",
      "allOf": [
       {
        "$ref": "#/components/schemas/EquivalentDocumentReference"
       }
      ]
     }
    },
    "required": [
     "items",
     "note_type",
     "concept",
     "equivalent_document"
    ]
   },
   "Extension": {
    "type": "object",
    "additionalProperties": false,
    "minProperties": 1,
    "maxProperties": 1,
    "description": "La información propia del tipo de documento equivalente: UNA clave, la de su `document_type` (cinema 25, show 27, games 30, transport 35, air 50, stock_exchange 55, public_services 60).",
    "properties": {
     "cinema": {
      "$ref": "#/components/schemas/CinemaExtension"
     },
     "show": {
      "$ref": "#/components/schemas/ShowExtension"
     },
     "games": {
      "$ref": "#/components/schemas/GamesExtension"
     },
     "transport": {
      "$ref": "#/components/schemas/TransportExtension"
     },
     "air": {
      "$ref": "#/components/schemas/AirExtension"
     },
     "stock_exchange": {
      "$ref": "#/components/schemas/StockExchangeExtension"
     },
     "public_services": {
      "$ref": "#/components/schemas/PublicServicesExtension"
     }
    }
   },
   "EquivalentDocumentReference": {
    "oneOf": [
     {
      "type": "object",
      "additionalProperties": false,
      "required": [
       "id"
      ],
      "properties": {
       "id": {
        "type": "string",
        "pattern": "^pos_[0-9a-f]{32}$"
       }
      }
     },
     {
      "type": "object",
      "additionalProperties": false,
      "required": [
       "number",
       "cude",
       "issue_date",
       "document_type"
      ],
      "properties": {
       "number": {
        "type": "string"
       },
       "cude": {
        "type": "string",
        "pattern": "^[0-9a-fA-F]{96}$"
       },
       "issue_date": {
        "type": "string",
        "format": "date"
       },
       "document_type": {
        "type": "string",
        "enum": [
         "20",
         "25",
         "27",
         "30",
         "35",
         "40",
         "45",
         "50",
         "55",
         "60"
        ]
       },
       "total": {
        "oneOf": [
         {
          "type": "string",
          "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
         },
         {
          "type": "number"
         }
        ],
        "description": "Número o texto decimal con punto («150000.50»)."
       }
      }
     }
    ]
   },
   "SupportDocumentReference": {
    "oneOf": [
     {
      "type": "object",
      "additionalProperties": false,
      "required": [
       "id"
      ],
      "properties": {
       "id": {
        "type": "string",
        "pattern": "^sd_[0-9a-f]{32}$"
       }
      }
     },
     {
      "type": "object",
      "additionalProperties": false,
      "required": [
       "number",
       "cuds",
       "issue_date"
      ],
      "properties": {
       "number": {
        "type": "string"
       },
       "cuds": {
        "type": "string",
        "pattern": "^[0-9a-fA-F]{96}$"
       },
       "issue_date": {
        "type": "string",
        "format": "date"
       },
       "total": {
        "oneOf": [
         {
          "type": "string",
          "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
         },
         {
          "type": "number"
         }
        ],
        "description": "Número o texto decimal con punto («150000.50»)."
       }
      }
     }
    ]
   },
   "SupportAdjustmentReference": {
    "oneOf": [
     {
      "type": "object",
      "additionalProperties": false,
      "required": [
       "id"
      ],
      "properties": {
       "id": {
        "type": "string",
        "pattern": "^sda_[0-9a-f]{32}$"
       }
      }
     },
     {
      "type": "object",
      "additionalProperties": false,
      "required": [
       "number",
       "cuds",
       "issue_date"
      ],
      "properties": {
       "number": {
        "type": "string"
       },
       "cuds": {
        "type": "string",
        "pattern": "^[0-9a-fA-F]{96}$"
       },
       "issue_date": {
        "type": "string",
        "format": "date"
       }
      }
     }
    ]
   },
   "PayrollInput": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "external_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9:._/-]{1,100}$",
      "description": "Tu identificador del documento: único entre los documentos API de la empresa y el ambiente. En las nóminas es único entre las nóminas y sus ajustes (aparte de las facturas y los eventos)."
     },
     "period": {
      "description": "El periodo que se liquida y el tiempo laborado (`time_worked` se calcula si no se manda: años de 360 días y meses de 30).",
      "allOf": [
       {
        "$ref": "#/components/schemas/PayrollPeriod"
       }
      ]
     },
     "pay_period": {
      "type": "string",
      "maxLength": 20,
      "description": "Periodo de nómina (tabla 5.5.1): \"1\" semanal, \"2\" decenal, \"3\" catorcenal, \"4\" quincenal, \"5\" mensual, \"6\" otro."
     },
     "currency": {
      "type": "string",
      "maxLength": 20,
      "description": "Moneda (ISO 4217). Por defecto COP; con otra va `exchange_rate`."
     },
     "exchange_rate": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Tasa de cambio a pesos. Obligatoria con una moneda distinta de COP y prohibida con COP."
     },
     "novelty": {
      "description": "El CUNE del documento con la novedad contractual, si la hay. Solo en la nómina.",
      "allOf": [
       {
        "$ref": "#/components/schemas/PayrollNovelty"
       }
      ]
     },
     "notes": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "maxItems": 20
     },
     "employee": {
      "description": "El trabajador. Sus datos solo salen en las respuestas a esta llave (la del empleador): nunca en webhooks, en el registro de peticiones ni en lo que se guarda de la idempotencia.",
      "allOf": [
       {
        "$ref": "#/components/schemas/PayrollEmployee"
       }
      ]
     },
     "payment": {
      "$ref": "#/components/schemas/PayrollPayment"
     },
     "payment_dates": {
      "type": "array",
      "items": {
       "type": "string",
       "format": "date"
      },
      "maxItems": 31,
      "description": "Las fechas de pago (1 a 31)."
     },
     "earnings": {
      "$ref": "#/components/schemas/PayrollEarnings"
     },
     "deductions": {
      "$ref": "#/components/schemas/PayrollDeductions"
     },
     "rounding": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Redondeo hasta 2.00; no suma a los totales."
     },
     "generation_place": {
      "description": "Dónde se generó el documento. Por defecto, el municipio de la empresa.",
      "allOf": [
       {
        "$ref": "#/components/schemas/PayrollPlace"
       }
      ]
     },
     "employer": {
      "description": "Solo si la empresa es persona natural: sus apellidos y nombres (si la razón social no se separa bien en «apellido1 apellido2 nombre1»).",
      "allOf": [
       {
        "$ref": "#/components/schemas/PayrollEmployer"
       }
      ]
     }
    },
    "required": [
     "period",
     "pay_period",
     "employee",
     "payment",
     "payment_dates",
     "earnings",
     "deductions"
    ]
   },
   "PayrollAdjustmentInput": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "external_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9:._/-]{1,100}$",
      "description": "Tu identificador del documento: único entre los documentos API de la empresa y el ambiente. En las nóminas es único entre las nóminas y sus ajustes (aparte de las facturas y los eventos)."
     },
     "type": {
      "type": "string",
      "enum": [
       "replace",
       "delete"
      ],
      "description": "\"replace\" (Reemplazar: el ajuste lleva todos los datos de la nómina menos `novelty`) o \"delete\" (Eliminar: solo `predecessor`, `notes`, `generation_place` y `employer`)."
     },
     "predecessor": {
      "description": "El documento que se ajusta: {\"id\": \"pr_…\"} (una nómina de Trevol) o {\"id\": \"pra_…\"} (otro ajuste, el último de la cadena), o sus datos {number, cune, issue_date}.",
      "allOf": [
       {
        "$ref": "#/components/schemas/PayrollReference"
       }
      ]
     },
     "period": {
      "$ref": "#/components/schemas/PayrollPeriod"
     },
     "pay_period": {
      "type": "string",
      "maxLength": 20
     },
     "currency": {
      "type": "string",
      "maxLength": 20
     },
     "exchange_rate": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Número o texto decimal con punto («150000.50»)."
     },
     "notes": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "maxItems": 20
     },
     "employee": {
      "$ref": "#/components/schemas/PayrollEmployee"
     },
     "payment": {
      "$ref": "#/components/schemas/PayrollPayment"
     },
     "payment_dates": {
      "type": "array",
      "items": {
       "type": "string",
       "format": "date"
      },
      "maxItems": 31
     },
     "earnings": {
      "$ref": "#/components/schemas/PayrollEarnings"
     },
     "deductions": {
      "$ref": "#/components/schemas/PayrollDeductions"
     },
     "rounding": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "true = redondeo al peso; o un valor entre -2.00 y 2.00."
     },
     "generation_place": {
      "$ref": "#/components/schemas/PayrollPlace"
     },
     "employer": {
      "$ref": "#/components/schemas/PayrollEmployer"
     }
    },
    "required": [
     "type",
     "predecessor"
    ]
   },
   "PayrollReference": {
    "oneOf": [
     {
      "type": "object",
      "additionalProperties": false,
      "required": [
       "id"
      ],
      "properties": {
       "id": {
        "type": "string",
        "pattern": "^pra?_[0-9a-f]{32}$"
       }
      }
     },
     {
      "type": "object",
      "additionalProperties": false,
      "required": [
       "number",
       "cune",
       "issue_date"
      ],
      "properties": {
       "number": {
        "type": "string"
       },
       "cune": {
        "type": "string",
        "pattern": "^[0-9a-fA-F]{96}$"
       },
       "issue_date": {
        "type": "string",
        "format": "date"
       }
      }
     }
    ]
   },
   "Payroll": {
    "type": "object",
    "description": "Una nómina electrónica individual (102). Archivos `xml`, `zip` y `dian_response`.",
    "properties": {
     "id": {
      "type": "string",
      "description": "pr_…"
     },
     "object": {
      "type": "string",
      "enum": [
       "payroll"
      ]
     },
     "environment": {
      "type": "string",
      "enum": [
       "test",
       "live"
      ]
     },
     "status": {
      "type": "string",
      "enum": [
       "pending",
       "sending",
       "validating",
       "accepted",
       "rejected",
       "error",
       "processing"
      ],
      "description": "`validating`: el set de pruebas de la DIAN (habilitación) recibió la nómina y todavía la valida; no es un error, responde 202 en las dos versiones y Trevol solo consulta (nunca reenvía). `processing`: solo en la versión 2026-10-22, la DIAN no contestó y Trevol sigue resolviendo el documento."
     },
     "number": {
      "type": [
       "string",
       "null"
      ]
     },
     "prefix": {
      "type": [
       "string",
       "null"
      ]
     },
     "external_id": {
      "type": [
       "string",
       "null"
      ]
     },
     "origin": {
      "type": "string",
      "enum": [
       "api",
       "app"
      ]
     },
     "cune": {
      "type": [
       "string",
       "null"
      ],
      "description": "El código único de la nómina (CUNE, 96 hex)."
     },
     "qr": {
      "type": [
       "string",
       "null"
      ]
     },
     "issued_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "submission": {
      "type": [
       "string",
       "null"
      ],
      "enum": [
       "sync",
       "test_set",
       null
      ],
      "description": "`sync`: SendNominaSync; `test_set`: el set de pruebas de habilitación."
     },
     "period": {
      "$ref": "#/components/schemas/PayrollPeriod"
     },
     "pay_period": {
      "type": "string",
      "maxLength": 20
     },
     "currency": {
      "type": "string",
      "maxLength": 20
     },
     "exchange_rate": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Tasa de cambio a pesos. Obligatoria con una moneda distinta de COP y prohibida con COP."
     },
     "novelty": {
      "$ref": "#/components/schemas/PayrollNovelty"
     },
     "notes": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "maxItems": 20
     },
     "employee": {
      "$ref": "#/components/schemas/PayrollEmployee"
     },
     "payment": {
      "$ref": "#/components/schemas/PayrollPayment"
     },
     "payment_dates": {
      "type": "array",
      "items": {
       "type": "string",
       "format": "date"
      },
      "maxItems": 31
     },
     "earnings": {
      "$ref": "#/components/schemas/PayrollEarnings"
     },
     "deductions": {
      "$ref": "#/components/schemas/PayrollDeductions"
     },
     "rounding": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Redondeo hasta 2.00; no suma a los totales."
     },
     "generation_place": {
      "$ref": "#/components/schemas/PayrollPlace"
     },
     "employer": {
      "$ref": "#/components/schemas/PayrollEmployer"
     },
     "totals": {
      "type": [
       "object",
       "null"
      ],
      "description": "Montos como texto decimal con 2 decimales. Null en un ajuste Eliminar.",
      "properties": {
       "earnings": {
        "type": "string"
       },
       "deductions": {
        "type": "string"
       },
       "net": {
        "type": "string"
       },
       "rounding": {
        "type": "string"
       }
      }
     },
     "dian": {
      "type": "object",
      "properties": {
       "status_code": {
        "type": [
         "string",
         "null"
        ]
       },
       "message": {
        "type": [
         "string",
         "null"
        ]
       },
       "rules": {
        "type": "array",
        "items": {
         "type": "object",
         "properties": {
          "code": {
           "type": "string"
          },
          "severity": {
           "type": "string",
           "enum": [
            "rejection",
            "notification"
           ]
          },
          "message": {
           "type": "string"
          },
          "area": {
           "type": "string"
          },
          "explanation": {
           "type": "string"
          },
          "fix": {
           "type": [
            "string",
            "null"
           ]
          },
          "field": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "files": {
      "type": "object",
      "description": "Qué archivos hay (…/xml, …/zip, …/dian_response). No hay PDF.",
      "properties": {
       "xml": {
        "type": "boolean"
       },
       "zip": {
        "type": "boolean"
       },
       "dian_response": {
        "type": "boolean"
       }
      }
     },
     "created_at": {
      "type": "string",
      "format": "date-time"
     },
     "updated_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     }
    }
   },
   "PayrollAdjustment": {
    "type": "object",
    "description": "Una nota de ajuste de nómina electrónica (103: Reemplazar o Eliminar). Archivos `xml`, `zip` y `dian_response`.",
    "properties": {
     "id": {
      "type": "string",
      "description": "pra_…"
     },
     "object": {
      "type": "string",
      "enum": [
       "payroll_adjustment"
      ]
     },
     "environment": {
      "type": "string",
      "enum": [
       "test",
       "live"
      ]
     },
     "status": {
      "type": "string",
      "enum": [
       "pending",
       "sending",
       "validating",
       "accepted",
       "rejected",
       "error",
       "processing"
      ],
      "description": "`validating`: el set de pruebas de la DIAN (habilitación) recibió la nómina y todavía la valida; no es un error, responde 202 en las dos versiones y Trevol solo consulta (nunca reenvía). `processing`: solo en la versión 2026-10-22, la DIAN no contestó y Trevol sigue resolviendo el documento."
     },
     "number": {
      "type": [
       "string",
       "null"
      ]
     },
     "prefix": {
      "type": [
       "string",
       "null"
      ]
     },
     "external_id": {
      "type": [
       "string",
       "null"
      ]
     },
     "origin": {
      "type": "string",
      "enum": [
       "api",
       "app"
      ]
     },
     "cune": {
      "type": [
       "string",
       "null"
      ],
      "description": "El código único de la nómina (CUNE, 96 hex)."
     },
     "qr": {
      "type": [
       "string",
       "null"
      ]
     },
     "issued_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "submission": {
      "type": [
       "string",
       "null"
      ],
      "enum": [
       "sync",
       "test_set",
       null
      ],
      "description": "`sync`: SendNominaSync; `test_set`: el set de pruebas de habilitación."
     },
     "type": {
      "type": [
       "string",
       "null"
      ],
      "enum": [
       "replace",
       "delete",
       null
      ]
     },
     "predecessor": {
      "anyOf": [
       {
        "$ref": "#/components/schemas/PayrollReference"
       },
       {
        "type": "null"
       }
      ]
     },
     "period": {
      "$ref": "#/components/schemas/PayrollPeriod"
     },
     "pay_period": {
      "type": "string",
      "maxLength": 20
     },
     "currency": {
      "type": "string",
      "maxLength": 20
     },
     "exchange_rate": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Tasa de cambio a pesos. Obligatoria con una moneda distinta de COP y prohibida con COP."
     },
     "notes": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "maxItems": 20
     },
     "employee": {
      "$ref": "#/components/schemas/PayrollEmployee"
     },
     "payment": {
      "$ref": "#/components/schemas/PayrollPayment"
     },
     "payment_dates": {
      "type": "array",
      "items": {
       "type": "string",
       "format": "date"
      },
      "maxItems": 31
     },
     "earnings": {
      "$ref": "#/components/schemas/PayrollEarnings"
     },
     "deductions": {
      "$ref": "#/components/schemas/PayrollDeductions"
     },
     "rounding": {
      "oneOf": [
       {
        "type": "string",
        "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
       },
       {
        "type": "number"
       }
      ],
      "description": "Redondeo hasta 2.00; no suma a los totales."
     },
     "generation_place": {
      "$ref": "#/components/schemas/PayrollPlace"
     },
     "employer": {
      "$ref": "#/components/schemas/PayrollEmployer"
     },
     "totals": {
      "type": [
       "object",
       "null"
      ],
      "description": "Montos como texto decimal con 2 decimales. Null en un ajuste Eliminar.",
      "properties": {
       "earnings": {
        "type": "string"
       },
       "deductions": {
        "type": "string"
       },
       "net": {
        "type": "string"
       },
       "rounding": {
        "type": "string"
       }
      }
     },
     "dian": {
      "type": "object",
      "properties": {
       "status_code": {
        "type": [
         "string",
         "null"
        ]
       },
       "message": {
        "type": [
         "string",
         "null"
        ]
       },
       "rules": {
        "type": "array",
        "items": {
         "type": "object",
         "properties": {
          "code": {
           "type": "string"
          },
          "severity": {
           "type": "string",
           "enum": [
            "rejection",
            "notification"
           ]
          },
          "message": {
           "type": "string"
          },
          "area": {
           "type": "string"
          },
          "explanation": {
           "type": "string"
          },
          "fix": {
           "type": [
            "string",
            "null"
           ]
          },
          "field": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "files": {
      "type": "object",
      "description": "Qué archivos hay (…/xml, …/zip, …/dian_response). No hay PDF.",
      "properties": {
       "xml": {
        "type": "boolean"
       },
       "zip": {
        "type": "boolean"
       },
       "dian_response": {
        "type": "boolean"
       }
      }
     },
     "created_at": {
      "type": "string",
      "format": "date-time"
     },
     "updated_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     }
    }
   },
   "RadianEventInput": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "external_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9:._/-]{1,100}$",
      "description": "Tu identificador del documento: único entre los documentos API de la empresa y el ambiente. En los eventos es único entre los eventos (aparte de las facturas y las nóminas)."
     },
     "event_code": {
      "type": "string",
      "maxLength": 20,
      "description": "\"030\" acuse de recibo, \"031\" reclamo, \"032\" recibo del bien o servicio, \"033\" aceptación expresa (las cuatro sobre una factura RECIBIDA) o \"034\" aceptación tácita (sobre una factura PROPIA a crédito). Los 035 a 051 necesitan un participante RADIAN y no están disponibles."
     },
     "invoice": {
      "description": "030–033: la factura RECIBIDA sobre la que va el evento (CUFE, número y quién la emitió). 034: la factura PROPIA por su CUFE, `{cufe, number?}` (solo esos dos), en lugar de `invoice_id`: sirve también para las facturas que no se emitieron con Trevol (las trae la sincronización con la DIAN). Si el CUFE es de una factura de Trevol, es lo mismo que mandar su `invoice_id`.",
      "allOf": [
       {
        "$ref": "#/components/schemas/ReceivedInvoice"
       }
      ]
     },
     "invoice_id": {
      "type": "string",
      "pattern": "^inv_[0-9a-f]{32}$",
      "description": "034: el id (`inv_…`) de una factura de Trevol: propia, validada, a crédito y que no sea de consumidor final. Va aparte de `invoice` para que cada esquema sea plano en los SDK. Para una factura que no se emitió con Trevol, usa `invoice: {cufe}` (exactamente uno de los dos)."
     },
     "claim": {
      "description": "Solo en el reclamo (031) y obligatorio en él: {code: \"01\" a \"04\", note?}.",
      "allOf": [
       {
        "$ref": "#/components/schemas/EventClaim"
       }
      ]
     },
     "software": {
      "type": "string",
      "enum": [
       "own",
       "dian_free"
      ],
      "description": "030–033: `own` (el Software Propio de la empresa, por defecto) o `dian_free` (el software gratuito de la DIAN). El 034 se firma con el Software Propio."
     },
     "provider": {
      "type": "string",
      "enum": [
       "dian",
       "company"
      ],
      "description": "030–033: quién es el proveedor tecnológico: `dian` (por defecto con `dian_free`) o `company` (por defecto con `own`)."
     }
    },
    "required": [
     "event_code"
    ]
   },
   "RadianEvent": {
    "type": "object",
    "description": "Un evento RADIAN 030–034 sobre una factura. Solo archivo `xml`. Un rechazo es final.",
    "properties": {
     "id": {
      "type": "string",
      "pattern": "^rev_[0-9a-f]{32}$"
     },
     "object": {
      "type": "string",
      "enum": [
       "radian_event"
      ]
     },
     "environment": {
      "type": "string",
      "enum": [
       "test",
       "live"
      ]
     },
     "status": {
      "type": "string",
      "enum": [
       "pending",
       "sending",
       "validating",
       "accepted",
       "rejected",
       "error",
       "processing"
      ],
      "description": "`validating`: la DIAN respondió 98 («en proceso de validación»); no es un error, responde 202 en las dos versiones y Trevol solo consulta (el 98 significa «no reenvíes»). `processing`: solo en la 2026-10-22, un envío en duda o el evento anterior que aún no aparece: Trevol lo sigue resolviendo. `error` incluye el envío en duda de la 2026-10-21."
     },
     "event_code": {
      "type": "string",
      "enum": [
       "030",
       "031",
       "032",
       "033",
       "034"
      ]
     },
     "number": {
      "type": [
       "string",
       "null"
      ]
     },
     "prefix": {
      "type": [
       "string",
       "null"
      ]
     },
     "external_id": {
      "type": [
       "string",
       "null"
      ]
     },
     "origin": {
      "type": "string",
      "enum": [
       "api",
       "app"
      ]
     },
     "cude": {
      "type": [
       "string",
       "null"
      ]
     },
     "issued_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "invoice": {
      "type": "object",
      "description": "030–033: la factura recibida (con el emisor). 034: {id, cufe, number} de la factura propia; sin `id` si no se emitió con Trevol (la trajo la sincronización con la DIAN).",
      "properties": {
       "id": {
        "type": "string"
       },
       "cufe": {
        "type": [
         "string",
         "null"
        ]
       },
       "number": {
        "type": [
         "string",
         "null"
        ]
       },
       "type": {
        "type": "string"
       },
       "issuer": {
        "$ref": "#/components/schemas/ReceivedInvoiceIssuer"
       },
       "acquirer_document_type": {
        "type": "string"
       }
      }
     },
     "claim": {
      "anyOf": [
       {
        "$ref": "#/components/schemas/EventClaim"
       },
       {
        "type": "null"
       }
      ]
     },
     "software": {
      "type": "string",
      "enum": [
       "own",
       "dian_free"
      ]
     },
     "provider": {
      "type": "string",
      "enum": [
       "dian",
       "company"
      ]
     },
     "dian": {
      "type": "object",
      "properties": {
       "status_code": {
        "type": [
         "string",
         "null"
        ]
       },
       "message": {
        "type": [
         "string",
         "null"
        ]
       },
       "rules": {
        "type": "array",
        "items": {
         "type": "object",
         "properties": {
          "code": {
           "type": "string"
          },
          "severity": {
           "type": "string",
           "enum": [
            "rejection",
            "notification"
           ]
          },
          "message": {
           "type": "string"
          },
          "area": {
           "type": "string"
          },
          "explanation": {
           "type": "string"
          },
          "fix": {
           "type": [
            "string",
            "null"
           ]
          },
          "field": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "already_registered": {
      "type": "boolean",
      "description": "true: GetStatusEvent ya mostraba el CUDE de ESTE evento (un envío en duda que sí llegó); se cerró `accepted` sin reenviar."
     },
     "already_registered_elsewhere": {
      "type": "boolean",
      "description": "true: la DIAN rechazó con LGC01, la factura ya tiene ese evento (quizá de otro software); no hace falta enviarlo."
     },
     "tacit": {
      "type": "boolean",
      "description": "033 rechazada con DC24c: la factura ya quedó aceptada tácitamente."
     },
     "created_at": {
      "type": "string",
      "format": "date-time"
     },
     "updated_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     }
    }
   },
   "TacitAcceptance": {
    "type": "object",
    "description": "¿Procede ya la aceptación tácita (034) sobre una factura propia? Solo lectura: consulta GetStatusEvent con el certificado de la empresa y no envía nada. Límite propio: 30 por minuto por llave (las dos consultas, juntas).",
    "properties": {
     "object": {
      "type": "string",
      "enum": [
       "tacit_acceptance"
      ]
     },
     "invoice_id": {
      "type": "string",
      "pattern": "^inv_[0-9a-f]{32}$",
      "description": "Solo si la factura es de Trevol."
     },
     "cufe": {
      "type": "string",
      "description": "El CUFE de la factura."
     },
     "number": {
      "type": "string",
      "description": "El número de la factura."
     },
     "allowed": {
      "type": "boolean"
     },
     "available_from": {
      "type": [
       "string",
       "null"
      ],
      "format": "date",
      "description": "Desde cuándo procede (3 días hábiles después del recibo del bien, 032)."
     },
     "rules": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "code": {
         "type": "string"
        },
        "severity": {
         "type": "string",
         "enum": [
          "rejection",
          "notification"
         ]
        },
        "message": {
         "type": "string"
        },
        "area": {
         "type": "string"
        },
        "explanation": {
         "type": "string"
        },
        "fix": {
         "type": [
          "string",
          "null"
         ]
        },
        "field": {
         "type": "string"
        },
        "local": {
         "type": "boolean",
         "description": "true: la regla la aplica Trevol (los 3 días hábiles), no la DIAN."
        }
       }
      },
      "description": "Las reglas (LGC…) que impiden el 034 ahora; llevan `local: true`."
     }
    }
   },
   "Document": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string",
      "description": "inv_… | cn_… | dn_…"
     },
     "object": {
      "type": "string",
      "enum": [
       "invoice",
       "credit_note",
       "debit_note"
      ]
     },
     "environment": {
      "type": "string",
      "enum": [
       "test",
       "live"
      ]
     },
     "status": {
      "type": "string",
      "enum": [
       "pending",
       "sending",
       "accepted",
       "rejected",
       "error",
       "contingency",
       "processing"
      ],
      "description": "`processing` solo en la versión 2026-10-22: la DIAN no confirmó y Trevol sigue resolviendo el documento (el resultado llega por GET y por webhook; no crees otro documento para la misma venta). En 2026-10-21 ese documento se ve como `error`."
     },
     "number": {
      "type": [
       "string",
       "null"
      ]
     },
     "prefix": {
      "type": [
       "string",
       "null"
      ]
     },
     "external_id": {
      "type": [
       "string",
       "null"
      ]
     },
     "origin": {
      "type": "string",
      "enum": [
       "api",
       "app",
       "contapyme"
      ]
     },
     "cufe": {
      "type": [
       "string",
       "null"
      ]
     },
     "cude": {
      "type": [
       "string",
       "null"
      ]
     },
     "qr": {
      "type": [
       "string",
       "null"
      ]
     },
     "issued_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "customer": {
      "$ref": "#/components/schemas/Customer"
     },
     "items": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Item"
      }
     },
     "payment": {
      "$ref": "#/components/schemas/Payment"
     },
     "invoice": {
      "$ref": "#/components/schemas/InvoiceReference"
     },
     "document_type": {
      "type": "string",
      "description": "Tipo de factura (tabla 13.1.3): 01 venta, 02 exportación."
     },
     "operation_type": {
      "type": "string",
      "description": "Tipo de operación (tabla 13.1.5.1)."
     },
     "currency": {
      "$ref": "#/components/schemas/Currency"
     },
     "cop_totals": {
      "type": "boolean"
     },
     "delivery_terms": {
      "$ref": "#/components/schemas/DeliveryTerms"
     },
     "shipment": {
      "$ref": "#/components/schemas/Shipment"
     },
     "due_diligence": {
      "type": "string",
      "description": "Debida diligencia (tabla 18.3)."
     },
     "interoperability": {
      "$ref": "#/components/schemas/Interoperability"
     },
     "totals": {
      "type": [
       "object",
       "null"
      ],
      "description": "Montos como texto decimal con 2 decimales, siempre en pesos. Con moneda extranjera, `currency` trae el equivalente.",
      "properties": {
       "subtotal": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "discounts": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "line_extension": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "tax_exclusive": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$",
        "description": "La base gravable (la de los impuestos)."
       },
       "taxes": {
        "type": "array",
        "items": {
         "type": "object",
         "properties": {
          "code": {
           "type": "string"
          },
          "name": {
           "type": [
            "string",
            "null"
           ]
          },
          "rate": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "base": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "amount": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          }
         }
        }
       },
       "allowances": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "charges": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "rounding": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "total": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "withholdings": {
        "type": "array",
        "items": {
         "type": "object",
         "properties": {
          "code": {
           "type": "string"
          },
          "name": {
           "type": [
            "string",
            "null"
           ]
          },
          "rate": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "base": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "amount": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "self_withholding": {
           "type": "boolean"
          }
         }
        }
       },
       "prepayments": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "net_payable": {
        "type": [
         "string",
         "null"
        ],
        "description": "Total menos retenciones y anticipos; null si no aplica."
       },
       "line_charges": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$",
        "description": "Solo si hay recargos en las líneas."
       },
       "items": {
        "type": "array",
        "description": "Una por línea, en el orden del pedido.",
        "items": {
         "type": "object",
         "properties": {
          "gross": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "discount": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "line_extension": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "charge": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "commercial_value": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          }
         }
        }
       },
       "currency": {
        "type": "object",
        "description": "Solo con moneda extranjera: el total en esa moneda y en pesos.",
        "properties": {
         "code": {
          "type": "string"
         },
         "exchange_rate": {
          "type": "string"
         },
         "rate_date": {
          "type": "string",
          "format": "date"
         },
         "total_currency": {
          "type": "string"
         },
         "total_cop": {
          "type": "string"
         }
        }
       }
      }
     },
     "dian": {
      "type": "object",
      "properties": {
       "status_code": {
        "type": [
         "string",
         "null"
        ]
       },
       "message": {
        "type": [
         "string",
         "null"
        ]
       },
       "rules": {
        "type": "array",
        "items": {
         "type": "object",
         "properties": {
          "code": {
           "type": "string"
          },
          "severity": {
           "type": "string",
           "enum": [
            "rejection",
            "notification"
           ]
          },
          "message": {
           "type": "string"
          },
          "area": {
           "type": "string"
          },
          "explanation": {
           "type": "string"
          },
          "fix": {
           "type": [
            "string",
            "null"
           ]
          },
          "field": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "delivery": {
      "$ref": "#/components/schemas/Delivery"
     },
     "created_at": {
      "type": "string",
      "format": "date-time"
     },
     "updated_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     }
    }
   },
   "SupportDocument": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string",
      "description": "sd_…"
     },
     "object": {
      "type": "string",
      "enum": [
       "support_document"
      ]
     },
     "environment": {
      "type": "string",
      "enum": [
       "test",
       "live"
      ]
     },
     "status": {
      "type": "string",
      "enum": [
       "pending",
       "sending",
       "accepted",
       "rejected",
       "error",
       "processing"
      ],
      "description": "`processing` solo en la versión 2026-10-22: la DIAN no confirmó y Trevol sigue resolviendo el documento (el resultado llega por GET y por webhook; no crees otro documento para la misma venta). En 2026-10-21 ese documento se ve como `error`."
     },
     "number": {
      "type": [
       "string",
       "null"
      ]
     },
     "prefix": {
      "type": [
       "string",
       "null"
      ]
     },
     "external_id": {
      "type": [
       "string",
       "null"
      ]
     },
     "origin": {
      "type": "string",
      "enum": [
       "api",
       "app",
       "contapyme"
      ]
     },
     "qr": {
      "type": [
       "string",
       "null"
      ]
     },
     "issued_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "items": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/SupportItem"
      }
     },
     "payment": {
      "$ref": "#/components/schemas/Payment"
     },
     "currency": {
      "$ref": "#/components/schemas/SupportCurrency"
     },
     "totals": {
      "type": [
       "object",
       "null"
      ],
      "description": "Montos como texto decimal con 2 decimales, siempre en pesos. Con moneda extranjera, `currency` trae el equivalente.",
      "properties": {
       "subtotal": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "discounts": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "line_extension": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "tax_exclusive": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$",
        "description": "La base gravable (la de los impuestos)."
       },
       "taxes": {
        "type": "array",
        "items": {
         "type": "object",
         "properties": {
          "code": {
           "type": "string"
          },
          "name": {
           "type": [
            "string",
            "null"
           ]
          },
          "rate": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "base": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "amount": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          }
         }
        }
       },
       "allowances": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "charges": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "rounding": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "total": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "withholdings": {
        "type": "array",
        "items": {
         "type": "object",
         "properties": {
          "code": {
           "type": "string"
          },
          "name": {
           "type": [
            "string",
            "null"
           ]
          },
          "rate": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "base": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "amount": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "self_withholding": {
           "type": "boolean"
          }
         }
        }
       },
       "prepayments": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "net_payable": {
        "type": [
         "string",
         "null"
        ],
        "description": "Total menos retenciones y anticipos; null si no aplica."
       },
       "line_charges": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$",
        "description": "Solo si hay recargos en las líneas."
       },
       "items": {
        "type": "array",
        "description": "Una por línea, en el orden del pedido.",
        "items": {
         "type": "object",
         "properties": {
          "gross": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "discount": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "line_extension": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "charge": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "commercial_value": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          }
         }
        }
       },
       "currency": {
        "type": "object",
        "description": "Solo con moneda extranjera: el total en esa moneda y en pesos.",
        "properties": {
         "code": {
          "type": "string"
         },
         "exchange_rate": {
          "type": "string"
         },
         "rate_date": {
          "type": "string",
          "format": "date"
         },
         "total_currency": {
          "type": "string"
         },
         "total_cop": {
          "type": "string"
         }
        }
       }
      }
     },
     "dian": {
      "type": "object",
      "properties": {
       "status_code": {
        "type": [
         "string",
         "null"
        ]
       },
       "message": {
        "type": [
         "string",
         "null"
        ]
       },
       "rules": {
        "type": "array",
        "items": {
         "type": "object",
         "properties": {
          "code": {
           "type": "string"
          },
          "severity": {
           "type": "string",
           "enum": [
            "rejection",
            "notification"
           ]
          },
          "message": {
           "type": "string"
          },
          "area": {
           "type": "string"
          },
          "explanation": {
           "type": "string"
          },
          "fix": {
           "type": [
            "string",
            "null"
           ]
          },
          "field": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "delivery": {
      "type": "object",
      "description": "El documento soporte se genera, no se expide: no hay PDF, ZIP ni correo. Solo hay XML y la respuesta de la DIAN.",
      "properties": {
       "status": {
        "type": "null"
       },
       "pdf": {
        "type": "boolean",
        "enum": [
         false
        ]
       },
       "zip": {
        "type": "boolean",
        "enum": [
         false
        ]
       },
       "xml": {
        "type": "boolean"
       },
       "email": {
        "type": "null"
       }
      }
     },
     "created_at": {
      "type": "string",
      "format": "date-time"
     },
     "updated_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "cuds": {
      "type": [
       "string",
       "null"
      ],
      "description": "El código único del documento (CUDS, 96 hex)."
     },
     "seller": {
      "$ref": "#/components/schemas/Seller"
     },
     "notes": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "references": {
      "$ref": "#/components/schemas/References"
     },
     "allowance_charges": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/AllowanceCharge"
      }
     },
     "transmission": {
      "type": "string",
      "enum": [
       "per_operation",
       "weekly"
      ]
     },
     "adjustment_note": {
      "anyOf": [
       {
        "$ref": "#/components/schemas/SupportAdjustmentReference"
       },
       {
        "type": "null"
       }
      ]
     }
    },
    "description": "Un documento soporte en adquisiciones a no obligados a facturar (Invoice 05). Se genera, no se expide: archivos `xml` y `dian_response`."
   },
   "SupportDocumentAdjustment": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string",
      "description": "sda_…"
     },
     "object": {
      "type": "string",
      "enum": [
       "support_document_adjustment"
      ]
     },
     "environment": {
      "type": "string",
      "enum": [
       "test",
       "live"
      ]
     },
     "status": {
      "type": "string",
      "enum": [
       "pending",
       "sending",
       "accepted",
       "rejected",
       "error",
       "processing"
      ],
      "description": "`processing` solo en la versión 2026-10-22: la DIAN no confirmó y Trevol sigue resolviendo el documento (el resultado llega por GET y por webhook; no crees otro documento para la misma venta). En 2026-10-21 ese documento se ve como `error`."
     },
     "number": {
      "type": [
       "string",
       "null"
      ]
     },
     "prefix": {
      "type": [
       "string",
       "null"
      ]
     },
     "external_id": {
      "type": [
       "string",
       "null"
      ]
     },
     "origin": {
      "type": "string",
      "enum": [
       "api",
       "app",
       "contapyme"
      ]
     },
     "qr": {
      "type": [
       "string",
       "null"
      ]
     },
     "issued_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "items": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/SupportAdjustmentItem"
      }
     },
     "payment": {
      "$ref": "#/components/schemas/Payment"
     },
     "currency": {
      "$ref": "#/components/schemas/SupportCurrency"
     },
     "totals": {
      "type": [
       "object",
       "null"
      ],
      "description": "Montos como texto decimal con 2 decimales, siempre en pesos. Con moneda extranjera, `currency` trae el equivalente.",
      "properties": {
       "subtotal": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "discounts": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "line_extension": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "tax_exclusive": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$",
        "description": "La base gravable (la de los impuestos)."
       },
       "taxes": {
        "type": "array",
        "items": {
         "type": "object",
         "properties": {
          "code": {
           "type": "string"
          },
          "name": {
           "type": [
            "string",
            "null"
           ]
          },
          "rate": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "base": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "amount": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          }
         }
        }
       },
       "allowances": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "charges": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "rounding": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "total": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "withholdings": {
        "type": "array",
        "items": {
         "type": "object",
         "properties": {
          "code": {
           "type": "string"
          },
          "name": {
           "type": [
            "string",
            "null"
           ]
          },
          "rate": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "base": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "amount": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "self_withholding": {
           "type": "boolean"
          }
         }
        }
       },
       "prepayments": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "net_payable": {
        "type": [
         "string",
         "null"
        ],
        "description": "Total menos retenciones y anticipos; null si no aplica."
       },
       "line_charges": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$",
        "description": "Solo si hay recargos en las líneas."
       },
       "items": {
        "type": "array",
        "description": "Una por línea, en el orden del pedido.",
        "items": {
         "type": "object",
         "properties": {
          "gross": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "discount": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "line_extension": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "charge": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "commercial_value": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          }
         }
        }
       },
       "currency": {
        "type": "object",
        "description": "Solo con moneda extranjera: el total en esa moneda y en pesos.",
        "properties": {
         "code": {
          "type": "string"
         },
         "exchange_rate": {
          "type": "string"
         },
         "rate_date": {
          "type": "string",
          "format": "date"
         },
         "total_currency": {
          "type": "string"
         },
         "total_cop": {
          "type": "string"
         }
        }
       }
      }
     },
     "dian": {
      "type": "object",
      "properties": {
       "status_code": {
        "type": [
         "string",
         "null"
        ]
       },
       "message": {
        "type": [
         "string",
         "null"
        ]
       },
       "rules": {
        "type": "array",
        "items": {
         "type": "object",
         "properties": {
          "code": {
           "type": "string"
          },
          "severity": {
           "type": "string",
           "enum": [
            "rejection",
            "notification"
           ]
          },
          "message": {
           "type": "string"
          },
          "area": {
           "type": "string"
          },
          "explanation": {
           "type": "string"
          },
          "fix": {
           "type": [
            "string",
            "null"
           ]
          },
          "field": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "delivery": {
      "type": "object",
      "description": "El documento soporte se genera, no se expide: no hay PDF, ZIP ni correo. Solo hay XML y la respuesta de la DIAN.",
      "properties": {
       "status": {
        "type": "null"
       },
       "pdf": {
        "type": "boolean",
        "enum": [
         false
        ]
       },
       "zip": {
        "type": "boolean",
        "enum": [
         false
        ]
       },
       "xml": {
        "type": "boolean"
       },
       "email": {
        "type": "null"
       }
      }
     },
     "created_at": {
      "type": "string",
      "format": "date-time"
     },
     "updated_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "cuds": {
      "type": [
       "string",
       "null"
      ],
      "description": "El código único del documento (CUDS, 96 hex)."
     },
     "seller": {
      "$ref": "#/components/schemas/Seller"
     },
     "notes": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "references": {
      "$ref": "#/components/schemas/References"
     },
     "allowance_charges": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/AllowanceCharge"
      }
     },
     "concept": {
      "type": "string",
      "description": "Concepto de la nota (tabla 16.2.4): 1 a 5."
     },
     "description": {
      "type": "string"
     },
     "support_document": {
      "$ref": "#/components/schemas/SupportDocumentReference"
     }
    },
    "description": "Una nota de ajuste de un documento soporte (CreditNote 95). Se genera, no se expide: archivos `xml` y `dian_response`."
   },
   "EquivalentDocument": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string",
      "description": "pos_… (todos los tipos de documento equivalente)"
     },
     "object": {
      "type": "string",
      "enum": [
       "equivalent_document"
      ]
     },
     "environment": {
      "type": "string",
      "enum": [
       "test",
       "live"
      ]
     },
     "status": {
      "type": "string",
      "enum": [
       "pending",
       "sending",
       "accepted",
       "rejected",
       "error",
       "contingency",
       "processing",
       "validating"
      ],
      "description": "`processing` solo en la versión 2026-10-22: la DIAN no confirmó y Trevol sigue resolviendo el documento (el resultado llega por GET y por webhook; no crees otro documento para la misma venta). En 2026-10-21 ese documento se ve como `error`. `validating`: el set de pruebas de la DIAN (habilitación) recibió el documento y todavía lo valida; no es un error, responde 202 en las dos versiones y Trevol solo consulta (nunca reenvía)."
     },
     "number": {
      "type": [
       "string",
       "null"
      ]
     },
     "prefix": {
      "type": [
       "string",
       "null"
      ]
     },
     "external_id": {
      "type": [
       "string",
       "null"
      ]
     },
     "origin": {
      "type": "string",
      "enum": [
       "api",
       "app",
       "contapyme"
      ]
     },
     "cude": {
      "type": [
       "string",
       "null"
      ],
      "description": "El código único del documento (CUDE, 96 hex)."
     },
     "qr": {
      "type": [
       "string",
       "null"
      ]
     },
     "issued_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "customer": {
      "$ref": "#/components/schemas/Customer"
     },
     "items": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/EquivalentItem"
      }
     },
     "payment": {
      "$ref": "#/components/schemas/Payment"
     },
     "document_type": {
      "type": "string",
      "enum": [
       "20",
       "25",
       "27",
       "30",
       "35",
       "40",
       "45",
       "50",
       "55",
       "60"
      ],
      "description": "Tipo de documento equivalente (tabla 16.3)."
     },
     "operation_type": {
      "type": "string",
      "description": "Tipo de operación (CustomizationID, tabla 16.4.1)."
     },
     "totals": {
      "type": [
       "object",
       "null"
      ],
      "description": "Montos como texto decimal con 2 decimales, siempre en pesos. Con moneda extranjera, `currency` trae el equivalente.",
      "properties": {
       "subtotal": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "discounts": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "line_extension": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "tax_exclusive": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$",
        "description": "La base gravable (la de los impuestos)."
       },
       "taxes": {
        "type": "array",
        "items": {
         "type": "object",
         "properties": {
          "code": {
           "type": "string"
          },
          "name": {
           "type": [
            "string",
            "null"
           ]
          },
          "rate": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "base": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "amount": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          }
         }
        }
       },
       "allowances": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "charges": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "rounding": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "total": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "withholdings": {
        "type": "array",
        "items": {
         "type": "object",
         "properties": {
          "code": {
           "type": "string"
          },
          "name": {
           "type": [
            "string",
            "null"
           ]
          },
          "rate": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "base": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "amount": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "self_withholding": {
           "type": "boolean"
          }
         }
        }
       },
       "prepayments": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "net_payable": {
        "type": [
         "string",
         "null"
        ],
        "description": "Total menos retenciones y anticipos; null si no aplica."
       },
       "line_charges": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$",
        "description": "Solo si hay recargos en las líneas."
       },
       "items": {
        "type": "array",
        "description": "Una por línea, en el orden del pedido.",
        "items": {
         "type": "object",
         "properties": {
          "gross": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "discount": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "line_extension": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "charge": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "commercial_value": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          }
         }
        }
       },
       "currency": {
        "type": "object",
        "description": "Solo con moneda extranjera: el total en esa moneda y en pesos.",
        "properties": {
         "code": {
          "type": "string"
         },
         "exchange_rate": {
          "type": "string"
         },
         "rate_date": {
          "type": "string",
          "format": "date"
         },
         "total_currency": {
          "type": "string"
         },
         "total_cop": {
          "type": "string"
         }
        }
       }
      }
     },
     "dian": {
      "type": "object",
      "properties": {
       "status_code": {
        "type": [
         "string",
         "null"
        ]
       },
       "message": {
        "type": [
         "string",
         "null"
        ]
       },
       "rules": {
        "type": "array",
        "items": {
         "type": "object",
         "properties": {
          "code": {
           "type": "string"
          },
          "severity": {
           "type": "string",
           "enum": [
            "rejection",
            "notification"
           ]
          },
          "message": {
           "type": "string"
          },
          "area": {
           "type": "string"
          },
          "explanation": {
           "type": "string"
          },
          "fix": {
           "type": [
            "string",
            "null"
           ]
          },
          "field": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "delivery": {
      "$ref": "#/components/schemas/Delivery"
     },
     "created_at": {
      "type": "string",
      "format": "date-time"
     },
     "updated_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "notes": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "period": {
      "$ref": "#/components/schemas/Period"
     },
     "references": {
      "$ref": "#/components/schemas/References"
     },
     "allowance_charges": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/AllowanceCharge"
      }
     },
     "prepayments": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Prepayment"
      }
     },
     "rounding": {
      "oneOf": [
       {
        "type": "boolean"
       },
       {
        "oneOf": [
         {
          "type": "string",
          "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
         },
         {
          "type": "number"
         }
        ],
        "description": "Número o texto decimal con punto («150000.50»)."
       }
      ]
     },
     "withholdings": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Withholding"
      }
     },
     "pos": {
      "$ref": "#/components/schemas/Pos"
     },
     "extension": {
      "$ref": "#/components/schemas/Extension"
     },
     "origin_note": {
      "$ref": "#/components/schemas/OriginNote"
     },
     "contingency": {
      "anyOf": [
       {
        "type": "object",
        "properties": {
         "type": {
          "type": "string",
          "enum": [
           "07",
           "08"
          ],
          "description": "07: el emisor transcribe un documento físico. 08: la DIAN no contestó (la decide Trevol)."
         },
         "physical_document": {
          "anyOf": [
           {
            "$ref": "#/components/schemas/PhysicalDocument"
           },
           {
            "type": "null"
           }
          ]
         },
         "backup": {
          "anyOf": [
           {
            "type": "object",
            "properties": {
             "type": {
              "type": "string",
              "enum": [
               "20"
              ],
              "description": "El respaldo POS 20 de una contingencia 08."
             },
             "at": {
              "type": [
               "string",
               "null"
              ],
              "format": "date-time"
             }
            }
           },
           {
            "type": "null"
           }
          ]
         }
        }
       },
       {
        "type": "null"
       }
      ]
     }
    },
    "description": "Un documento equivalente electrónico (tiquete POS 20 y los demás tipos de la tabla 16.3). Se expide como la factura: archivos `pdf`, `xml`, `zip` y `dian_response`."
   },
   "EquivalentDocumentAdjustment": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string",
      "description": "posa_…"
     },
     "object": {
      "type": "string",
      "enum": [
       "equivalent_document_adjustment"
      ]
     },
     "environment": {
      "type": "string",
      "enum": [
       "test",
       "live"
      ]
     },
     "status": {
      "type": "string",
      "enum": [
       "pending",
       "sending",
       "accepted",
       "rejected",
       "error",
       "contingency",
       "processing",
       "validating"
      ],
      "description": "`processing` solo en la versión 2026-10-22: la DIAN no confirmó y Trevol sigue resolviendo el documento (el resultado llega por GET y por webhook; no crees otro documento para la misma venta). En 2026-10-21 ese documento se ve como `error`. `validating`: el set de pruebas de la DIAN (habilitación) recibió el documento y todavía lo valida; no es un error, responde 202 en las dos versiones y Trevol solo consulta (nunca reenvía)."
     },
     "number": {
      "type": [
       "string",
       "null"
      ]
     },
     "prefix": {
      "type": [
       "string",
       "null"
      ]
     },
     "external_id": {
      "type": [
       "string",
       "null"
      ]
     },
     "origin": {
      "type": "string",
      "enum": [
       "api",
       "app",
       "contapyme"
      ]
     },
     "cude": {
      "type": [
       "string",
       "null"
      ],
      "description": "El código único del documento (CUDE, 96 hex)."
     },
     "qr": {
      "type": [
       "string",
       "null"
      ]
     },
     "issued_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "customer": {
      "$ref": "#/components/schemas/Customer"
     },
     "items": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/EquivalentAdjustmentItem"
      }
     },
     "payment": {
      "$ref": "#/components/schemas/Payment"
     },
     "totals": {
      "type": [
       "object",
       "null"
      ],
      "description": "Montos como texto decimal con 2 decimales, siempre en pesos. Con moneda extranjera, `currency` trae el equivalente.",
      "properties": {
       "subtotal": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "discounts": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "line_extension": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "tax_exclusive": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$",
        "description": "La base gravable (la de los impuestos)."
       },
       "taxes": {
        "type": "array",
        "items": {
         "type": "object",
         "properties": {
          "code": {
           "type": "string"
          },
          "name": {
           "type": [
            "string",
            "null"
           ]
          },
          "rate": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "base": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "amount": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          }
         }
        }
       },
       "allowances": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "charges": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "rounding": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "total": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "withholdings": {
        "type": "array",
        "items": {
         "type": "object",
         "properties": {
          "code": {
           "type": "string"
          },
          "name": {
           "type": [
            "string",
            "null"
           ]
          },
          "rate": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "base": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "amount": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "self_withholding": {
           "type": "boolean"
          }
         }
        }
       },
       "prepayments": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$"
       },
       "net_payable": {
        "type": [
         "string",
         "null"
        ],
        "description": "Total menos retenciones y anticipos; null si no aplica."
       },
       "line_charges": {
        "type": "string",
        "pattern": "^-?\\d+\\.\\d{2}$",
        "description": "Solo si hay recargos en las líneas."
       },
       "items": {
        "type": "array",
        "description": "Una por línea, en el orden del pedido.",
        "items": {
         "type": "object",
         "properties": {
          "gross": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "discount": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "line_extension": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "charge": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          },
          "commercial_value": {
           "type": "string",
           "pattern": "^-?\\d+\\.\\d{2}$"
          }
         }
        }
       },
       "currency": {
        "type": "object",
        "description": "Solo con moneda extranjera: el total en esa moneda y en pesos.",
        "properties": {
         "code": {
          "type": "string"
         },
         "exchange_rate": {
          "type": "string"
         },
         "rate_date": {
          "type": "string",
          "format": "date"
         },
         "total_currency": {
          "type": "string"
         },
         "total_cop": {
          "type": "string"
         }
        }
       }
      }
     },
     "dian": {
      "type": "object",
      "properties": {
       "status_code": {
        "type": [
         "string",
         "null"
        ]
       },
       "message": {
        "type": [
         "string",
         "null"
        ]
       },
       "rules": {
        "type": "array",
        "items": {
         "type": "object",
         "properties": {
          "code": {
           "type": "string"
          },
          "severity": {
           "type": "string",
           "enum": [
            "rejection",
            "notification"
           ]
          },
          "message": {
           "type": "string"
          },
          "area": {
           "type": "string"
          },
          "explanation": {
           "type": "string"
          },
          "fix": {
           "type": [
            "string",
            "null"
           ]
          },
          "field": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "delivery": {
      "$ref": "#/components/schemas/Delivery"
     },
     "created_at": {
      "type": "string",
      "format": "date-time"
     },
     "updated_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "notes": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "period": {
      "$ref": "#/components/schemas/Period"
     },
     "references": {
      "$ref": "#/components/schemas/References"
     },
     "allowance_charges": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/AllowanceCharge"
      }
     },
     "prepayments": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Prepayment"
      }
     },
     "rounding": {
      "oneOf": [
       {
        "type": "boolean"
       },
       {
        "oneOf": [
         {
          "type": "string",
          "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$"
         },
         {
          "type": "number"
         }
        ],
        "description": "Número o texto decimal con punto («150000.50»)."
       }
      ]
     },
     "note_type": {
      "type": "string",
      "enum": [
       "credit",
       "debit"
      ]
     },
     "concept": {
      "type": "string",
      "description": "Concepto de la nota (tabla 16.6): 1 a 5."
     },
     "description": {
      "type": "string"
     },
     "equivalent_document": {
      "$ref": "#/components/schemas/EquivalentDocumentReference"
     }
    },
    "description": "Una nota de ajuste de un documento equivalente (crédito 94 o débito 93). Se expide como la factura: archivos `pdf`, `xml`, `zip` y `dian_response`."
   },
   "Delivery": {
    "type": "object",
    "description": "Con la versión 2026-10-22, el PDF, el ZIP y el correo se hacen en segundo plano después del 201: casi siempre llegan `pending` y se completan en segundos (GET o el evento `….delivered`). Si pides …/pdf o …/zip antes, se generan al momento. Con la 2026-10-21 se hacen antes del 201, como en la fase 1.",
    "properties": {
     "status": {
      "type": [
       "string",
       "null"
      ],
      "enum": [
       "pending",
       "completed",
       null
      ],
      "description": "null si el documento no está `accepted`; `completed` con PDF, ZIP y un correo en estado final (sent, skipped, failed, bounced o complained)."
     },
     "pdf": {
      "type": "boolean"
     },
     "zip": {
      "type": "boolean"
     },
     "xml": {
      "type": "boolean"
     },
     "email": {
      "type": [
       "object",
       "null"
      ],
      "properties": {
       "status": {
        "type": "string",
        "enum": [
         "pending",
         "sent",
         "failed",
         "skipped",
         "bounced",
         "complained"
        ]
       },
       "to": {
        "type": [
         "string",
         "null"
        ]
       },
       "detail": {
        "type": [
         "string",
         "null"
        ]
       }
      }
     }
    }
   },
   "RequestLog": {
    "type": "object",
    "description": "Una petición de la API (sin cuerpo, consulta, IP ni llave). Se guardan 30 días y son las de la empresa y el ambiente de la llave.",
    "required": [
     "object",
     "id",
     "method",
     "path",
     "status",
     "duration_ms",
     "created_at"
    ],
    "properties": {
     "object": {
      "type": "string",
      "enum": [
       "request"
      ]
     },
     "id": {
      "type": "string",
      "pattern": "^req_[0-9a-f]{24}$",
      "description": "El `Request-Id` de la respuesta: compártelo si pides ayuda."
     },
     "method": {
      "type": "string",
      "enum": [
       "GET",
       "POST",
       "PUT",
       "PATCH",
       "DELETE"
      ]
     },
     "path": {
      "type": "string",
      "description": "La plantilla de la ruta, no la ruta real: /v1/invoices/{id}/pdf"
     },
     "status": {
      "type": "integer",
      "description": "El estado HTTP que se respondió."
     },
     "code": {
      "type": [
       "string",
       "null"
      ],
      "description": "El `code` del error (validation_error…); null si salió bien."
     },
     "duration_ms": {
      "type": "integer",
      "description": "Lo que tardó Trevol en responder, en milisegundos."
     },
     "key_id": {
      "type": [
       "string",
       "null"
      ],
      "description": "La llave que hizo la petición (key_…, la de GET /v1/company); null si ya se borró."
     },
     "document_id": {
      "type": [
       "string",
       "null"
      ],
      "description": "El documento (inv_…, cn_…, dn_…) sobre el que se actuó, si lo hay."
     },
     "idempotent_replayed": {
      "type": "boolean",
      "description": "Se respondió con el resultado guardado de una Idempotency-Key repetida."
     },
     "api_version": {
      "type": [
       "string",
       "null"
      ],
      "enum": [
       "2026-10-21",
       "2026-10-22",
       null
      ]
     },
     "created_at": {
      "type": "string",
      "format": "date-time"
     }
    }
   },
   "Preview": {
    "type": "object",
    "additionalProperties": true,
    "description": "El resultado de calcular sin emitir: el documento que se emitiría, con sus totales. No gasta numeración, saldo ni le manda nada a la DIAN. Lleva además los campos del pedido normalizados (cambian de un tipo de documento a otro).",
    "properties": {
     "object": {
      "type": "string",
      "enum": [
       "preview"
      ]
     },
     "document": {
      "type": "string",
      "description": "El `object` del documento que se emitiría (`invoice`, `credit_note`, `payroll`…)."
     },
     "environment": {
      "type": [
       "string",
       "null"
      ],
      "enum": [
       "test",
       "live",
       null
      ]
     },
     "totals": {
      "type": "object",
      "additionalProperties": true,
      "description": "Los totales calculados: la misma forma que `totals` del documento (en nómina, devengados, deducciones y total del comprobante)."
     }
    }
   },
   "Company": {
    "type": "object",
    "description": "La empresa de la llave, su ambiente y sus numeraciones activas.",
    "properties": {
     "object": {
      "type": "string",
      "enum": [
       "company"
      ]
     },
     "id": {
      "type": "string",
      "pattern": "^com_[0-9a-f]{32}$"
     },
     "nit": {
      "type": [
       "string",
       "null"
      ]
     },
     "check_digit": {
      "type": [
       "integer",
       "null"
      ]
     },
     "name": {
      "type": [
       "string",
       "null"
      ],
      "description": "La razón social."
     },
     "trade_name": {
      "type": [
       "string",
       "null"
      ]
     },
     "status": {
      "type": "string",
      "enum": [
       "enabled",
       "not_enabled"
      ]
     },
     "environment": {
      "type": [
       "string",
       "null"
      ],
      "enum": [
       "test",
       "live",
       null
      ]
     },
     "numbering": {
      "type": "array",
      "description": "Las numeraciones (resoluciones) activas del ambiente de la llave.",
      "items": {
       "type": "object",
       "properties": {
        "prefix": {
         "type": [
          "string",
          "null"
         ]
        },
        "resolution_number": {
         "type": [
          "string",
          "null"
         ]
        },
        "from": {
         "type": [
          "integer",
          "null"
         ]
        },
        "to": {
         "type": [
          "integer",
          "null"
         ]
        },
        "valid_to": {
         "type": [
          "string",
          "null"
         ],
         "format": "date"
        }
       }
      }
     },
     "key": {
      "type": "object",
      "description": "La llave con que se llamó.",
      "properties": {
       "id": {
        "type": "string",
        "pattern": "^key_[0-9a-f]{32}$"
       },
       "permissions": {
        "type": [
         "string",
         "null"
        ],
        "enum": [
         "write",
         "read",
         null
        ]
       },
       "api_version": {
        "type": "string",
        "enum": [
         "2026-10-21",
         "2026-10-22"
        ]
       }
      }
     },
     "capabilities": {
      "type": "object",
      "additionalProperties": true,
      "description": "Lo que ESTA llave puede emitir ahora (documento soporte, equivalente, nómina, eventos RADIAN). Informativo: si una lectura falla, esa clave no aparece."
     }
    }
   },
   "Acquirer": {
    "type": "object",
    "description": "El adquiriente como lo tiene la DIAN (y su correo, si lo conoce).",
    "properties": {
     "object": {
      "type": "string",
      "enum": [
       "acquirer"
      ]
     },
     "document_type": {
      "type": "string"
     },
     "document_number": {
      "type": "string"
     },
     "found": {
      "type": "boolean"
     },
     "name": {
      "type": [
       "string",
       "null"
      ]
     },
     "email": {
      "type": [
       "string",
       "null"
      ]
     }
    }
   },
   "WebhookEndpoint": {
    "type": "object",
    "required": [
     "id",
     "object",
     "environment",
     "url",
     "events",
     "status"
    ],
    "properties": {
     "id": {
      "type": "string",
      "pattern": "^we_[0-9a-f]{32}$"
     },
     "object": {
      "type": "string",
      "enum": [
       "webhook_endpoint"
      ]
     },
     "environment": {
      "type": "string",
      "enum": [
       "test",
       "live"
      ]
     },
     "url": {
      "type": "string",
      "maxLength": 500,
      "format": "uri",
      "description": "La URL completa solo la ven las llaves de escritura; las de lectura ven el esquema y el host (el camino va enmascarado: a veces es un secreto)."
     },
     "description": {
      "type": [
       "string",
       "null"
      ]
     },
     "events": {
      "type": "array",
      "minItems": 1,
      "maxItems": 60,
      "uniqueItems": true,
      "items": {
       "type": "string",
       "enum": [
        "*",
        "invoice.accepted",
        "invoice.rejected",
        "invoice.error",
        "invoice.delivered",
        "invoice.email_bounced",
        "invoice.email_failed",
        "credit_note.accepted",
        "credit_note.rejected",
        "credit_note.error",
        "credit_note.delivered",
        "credit_note.email_bounced",
        "credit_note.email_failed",
        "debit_note.accepted",
        "debit_note.rejected",
        "debit_note.error",
        "debit_note.delivered",
        "debit_note.email_bounced",
        "debit_note.email_failed",
        "balance.low",
        "numbering.low",
        "numbering.expiring",
        "certificate.expiring",
        "support_document.accepted",
        "support_document.rejected",
        "support_document.error",
        "support_document_adjustment.accepted",
        "support_document_adjustment.rejected",
        "support_document_adjustment.error",
        "equivalent_document.accepted",
        "equivalent_document.rejected",
        "equivalent_document.error",
        "equivalent_document.delivered",
        "equivalent_document.email_bounced",
        "equivalent_document.email_failed",
        "equivalent_document_adjustment.accepted",
        "equivalent_document_adjustment.rejected",
        "equivalent_document_adjustment.error",
        "equivalent_document_adjustment.delivered",
        "equivalent_document_adjustment.email_bounced",
        "equivalent_document_adjustment.email_failed",
        "payroll.accepted",
        "payroll.rejected",
        "payroll.error",
        "payroll_adjustment.accepted",
        "payroll_adjustment.rejected",
        "payroll_adjustment.error",
        "radian_event.accepted",
        "radian_event.rejected",
        "radian_event.error"
       ]
      },
      "description": "Eventos del catálogo (49 tipos, hasta 60 en la lista), o [\"*\"] para todos (no se mezcla). `balance.low`, `numbering.low` y `numbering.expiring` solo existen en producción (llaves live). `webhook.test` no se suscribe."
     },
     "catalog_version": {
      "type": "integer",
      "enum": [
       1,
       2
      ],
      "description": "Qué catálogo recibe con `[\"*\"]`: `1` = el de la fase 2 (facturas, notas, saldo, numeración y certificado); `2` = también documento soporte, documento equivalente, nómina y eventos RADIAN. Los endpoints creados antes de la fase 3 quedan en 1 hasta que guardes de nuevo su lista de eventos (PATCH `events`); los nuevos nacen en 2. Una lista explícita siempre recibe lo que pide."
     },
     "status": {
      "type": "string",
      "enum": [
       "enabled",
       "paused",
       "disabled"
      ],
      "description": "`paused`: lo pausaste tú. `disabled`: lo desactivó Trevol por fallos sostenidos (10 seguidos durante 5 días); se reactiva con PATCH status=enabled."
     },
     "disabled_reason": {
      "type": [
       "string",
       "null"
      ],
      "enum": [
       "sustained_failures",
       null
      ]
     },
     "secret_rotated_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "created_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "updated_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "secret": {
      "type": "string",
      "pattern": "^whsec_",
      "description": "SOLO al crear o rotar, una única vez: guárdalo. Verifica cada entrega con él (Standard Webhooks)."
     }
    }
   },
   "DeletedObject": {
    "type": "object",
    "required": [
     "id",
     "object",
     "deleted"
    ],
    "properties": {
     "id": {
      "type": "string"
     },
     "object": {
      "type": "string"
     },
     "deleted": {
      "type": "boolean",
      "enum": [
       true
      ]
     }
    }
   },
   "WebhookEndpointInput": {
    "type": "object",
    "additionalProperties": false,
    "required": [
     "url",
     "events"
    ],
    "properties": {
     "url": {
      "type": "string",
      "maxLength": 500,
      "format": "uri",
      "description": "https:// con un nombre de dominio (no una IP), sin usuario ni clave, puerto 443 o 1024–65535. En cada intento se resuelve el nombre y se rechaza toda dirección privada o local."
     },
     "description": {
      "type": [
       "string",
       "null"
      ],
      "maxLength": 120
     },
     "events": {
      "type": "array",
      "minItems": 1,
      "maxItems": 60,
      "uniqueItems": true,
      "items": {
       "type": "string",
       "enum": [
        "*",
        "invoice.accepted",
        "invoice.rejected",
        "invoice.error",
        "invoice.delivered",
        "invoice.email_bounced",
        "invoice.email_failed",
        "credit_note.accepted",
        "credit_note.rejected",
        "credit_note.error",
        "credit_note.delivered",
        "credit_note.email_bounced",
        "credit_note.email_failed",
        "debit_note.accepted",
        "debit_note.rejected",
        "debit_note.error",
        "debit_note.delivered",
        "debit_note.email_bounced",
        "debit_note.email_failed",
        "balance.low",
        "numbering.low",
        "numbering.expiring",
        "certificate.expiring",
        "support_document.accepted",
        "support_document.rejected",
        "support_document.error",
        "support_document_adjustment.accepted",
        "support_document_adjustment.rejected",
        "support_document_adjustment.error",
        "equivalent_document.accepted",
        "equivalent_document.rejected",
        "equivalent_document.error",
        "equivalent_document.delivered",
        "equivalent_document.email_bounced",
        "equivalent_document.email_failed",
        "equivalent_document_adjustment.accepted",
        "equivalent_document_adjustment.rejected",
        "equivalent_document_adjustment.error",
        "equivalent_document_adjustment.delivered",
        "equivalent_document_adjustment.email_bounced",
        "equivalent_document_adjustment.email_failed",
        "payroll.accepted",
        "payroll.rejected",
        "payroll.error",
        "payroll_adjustment.accepted",
        "payroll_adjustment.rejected",
        "payroll_adjustment.error",
        "radian_event.accepted",
        "radian_event.rejected",
        "radian_event.error"
       ]
      },
      "description": "Eventos del catálogo (49 tipos, hasta 60 en la lista), o [\"*\"] para todos (no se mezcla). `balance.low`, `numbering.low` y `numbering.expiring` solo existen en producción (llaves live). `webhook.test` no se suscribe."
     }
    }
   },
   "WebhookEndpointUpdate": {
    "type": "object",
    "additionalProperties": false,
    "minProperties": 1,
    "properties": {
     "url": {
      "type": "string",
      "maxLength": 500,
      "format": "uri",
      "description": "https:// con un nombre de dominio (no una IP), sin usuario ni clave, puerto 443 o 1024–65535. En cada intento se resuelve el nombre y se rechaza toda dirección privada o local."
     },
     "description": {
      "type": [
       "string",
       "null"
      ],
      "maxLength": 120
     },
     "events": {
      "type": "array",
      "minItems": 1,
      "maxItems": 60,
      "uniqueItems": true,
      "items": {
       "type": "string",
       "enum": [
        "*",
        "invoice.accepted",
        "invoice.rejected",
        "invoice.error",
        "invoice.delivered",
        "invoice.email_bounced",
        "invoice.email_failed",
        "credit_note.accepted",
        "credit_note.rejected",
        "credit_note.error",
        "credit_note.delivered",
        "credit_note.email_bounced",
        "credit_note.email_failed",
        "debit_note.accepted",
        "debit_note.rejected",
        "debit_note.error",
        "debit_note.delivered",
        "debit_note.email_bounced",
        "debit_note.email_failed",
        "balance.low",
        "numbering.low",
        "numbering.expiring",
        "certificate.expiring",
        "support_document.accepted",
        "support_document.rejected",
        "support_document.error",
        "support_document_adjustment.accepted",
        "support_document_adjustment.rejected",
        "support_document_adjustment.error",
        "equivalent_document.accepted",
        "equivalent_document.rejected",
        "equivalent_document.error",
        "equivalent_document.delivered",
        "equivalent_document.email_bounced",
        "equivalent_document.email_failed",
        "equivalent_document_adjustment.accepted",
        "equivalent_document_adjustment.rejected",
        "equivalent_document_adjustment.error",
        "equivalent_document_adjustment.delivered",
        "equivalent_document_adjustment.email_bounced",
        "equivalent_document_adjustment.email_failed",
        "payroll.accepted",
        "payroll.rejected",
        "payroll.error",
        "payroll_adjustment.accepted",
        "payroll_adjustment.rejected",
        "payroll_adjustment.error",
        "radian_event.accepted",
        "radian_event.rejected",
        "radian_event.error"
       ]
      },
      "description": "Eventos del catálogo (49 tipos, hasta 60 en la lista), o [\"*\"] para todos (no se mezcla). `balance.low`, `numbering.low` y `numbering.expiring` solo existen en producción (llaves live). `webhook.test` no se suscribe."
     },
     "status": {
      "type": "string",
      "enum": [
       "enabled",
       "paused"
      ],
      "description": "enabled reactiva (también uno desactivado por Trevol) y pone en cero el contador de fallos."
     }
    }
   },
   "Event": {
    "type": "object",
    "description": "Exactamente lo que se manda al endpoint (los bytes firmados) y lo que devuelve GET /v1/events. El mismo `id` (también en la cabecera `webhook-id`) llega en cada reintento y en un reenvío manual: úsalo para no procesar dos veces el mismo evento.",
    "required": [
     "id",
     "object",
     "type",
     "timestamp",
     "environment",
     "api_version",
     "data"
    ],
    "properties": {
     "id": {
      "type": "string",
      "pattern": "^evt_[0-9a-f]{32}$"
     },
     "object": {
      "type": "string",
      "enum": [
       "event"
      ]
     },
     "type": {
      "type": "string",
      "enum": [
       "invoice.accepted",
       "invoice.rejected",
       "invoice.error",
       "invoice.delivered",
       "invoice.email_bounced",
       "invoice.email_failed",
       "credit_note.accepted",
       "credit_note.rejected",
       "credit_note.error",
       "credit_note.delivered",
       "credit_note.email_bounced",
       "credit_note.email_failed",
       "debit_note.accepted",
       "debit_note.rejected",
       "debit_note.error",
       "debit_note.delivered",
       "debit_note.email_bounced",
       "debit_note.email_failed",
       "balance.low",
       "numbering.low",
       "numbering.expiring",
       "certificate.expiring",
       "support_document.accepted",
       "support_document.rejected",
       "support_document.error",
       "support_document_adjustment.accepted",
       "support_document_adjustment.rejected",
       "support_document_adjustment.error",
       "equivalent_document.accepted",
       "equivalent_document.rejected",
       "equivalent_document.error",
       "equivalent_document.delivered",
       "equivalent_document.email_bounced",
       "equivalent_document.email_failed",
       "equivalent_document_adjustment.accepted",
       "equivalent_document_adjustment.rejected",
       "equivalent_document_adjustment.error",
       "equivalent_document_adjustment.delivered",
       "equivalent_document_adjustment.email_bounced",
       "equivalent_document_adjustment.email_failed",
       "payroll.accepted",
       "payroll.rejected",
       "payroll.error",
       "payroll_adjustment.accepted",
       "payroll_adjustment.rejected",
       "payroll_adjustment.error",
       "radian_event.accepted",
       "radian_event.rejected",
       "radian_event.error",
       "webhook.test"
      ]
     },
     "timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "UTC."
     },
     "environment": {
      "type": "string",
      "enum": [
       "test",
       "live"
      ]
     },
     "api_version": {
      "type": "string",
      "description": "La versión vigente más nueva de la API; el resumen del documento no cambia con la versión de la llave."
     },
     "data": {
      "oneOf": [
       {
        "$ref": "#/components/schemas/DocumentEventData"
       },
       {
        "$ref": "#/components/schemas/SupportDocumentEventData"
       },
       {
        "$ref": "#/components/schemas/EquivalentDocumentEventData"
       },
       {
        "$ref": "#/components/schemas/PayrollEventData"
       },
       {
        "$ref": "#/components/schemas/RadianEventData"
       },
       {
        "$ref": "#/components/schemas/BalanceEventData"
       },
       {
        "$ref": "#/components/schemas/NumberingLowEventData"
       },
       {
        "$ref": "#/components/schemas/NumberingExpiringEventData"
       },
       {
        "$ref": "#/components/schemas/CertificateEventData"
       },
       {
        "$ref": "#/components/schemas/TestEventData"
       }
      ]
     }
    }
   },
   "DocumentEventData": {
    "type": "object",
    "description": "Resumen de un documento. Pide el documento completo con GET /v1/{invoices|credit_notes|debit_notes}/{id}.",
    "required": [
     "object",
     "id",
     "status",
     "environment",
     "dian",
     "delivery"
    ],
    "properties": {
     "object": {
      "type": "string",
      "enum": [
       "invoice",
       "credit_note",
       "debit_note"
      ]
     },
     "id": {
      "type": "string",
      "description": "inv_… | cn_… | dn_… (el mismo de la respuesta de la API)."
     },
     "status": {
      "type": "string",
      "enum": [
       "pending",
       "sending",
       "accepted",
       "rejected",
       "error",
       "contingency"
      ],
      "description": "Nunca `processing`: ese estado solo existe en las respuestas de la API."
     },
     "environment": {
      "type": "string",
      "enum": [
       "test",
       "live"
      ]
     },
     "number": {
      "type": [
       "string",
       "null"
      ]
     },
     "prefix": {
      "type": [
       "string",
       "null"
      ]
     },
     "external_id": {
      "type": [
       "string",
       "null"
      ],
      "description": "Tu identificador, solo en los documentos creados por la API."
     },
     "origin": {
      "type": "string",
      "enum": [
       "api",
       "app",
       "contapyme"
      ]
     },
     "cufe": {
      "type": [
       "string",
       "null"
      ],
      "description": "En las facturas."
     },
     "cude": {
      "type": [
       "string",
       "null"
      ],
      "description": "En las notas crédito y débito."
     },
     "issued_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "total": {
      "type": [
       "string",
       "null"
      ],
      "description": "Texto decimal con dos decimales."
     },
     "invoice": {
      "type": [
       "object",
       "null"
      ],
      "description": "En las notas: la factura de Trevol que corrigen.",
      "properties": {
       "id": {
        "type": "string",
        "pattern": "^inv_[0-9a-f]{32}$"
       }
      }
     },
     "dian": {
      "type": "object",
      "properties": {
       "status_code": {
        "type": [
         "string",
         "null"
        ]
       },
       "rules": {
        "type": "array",
        "maxItems": 20,
        "description": "Los códigos de las reglas de la DIAN, con las de rechazo primero.",
        "items": {
         "type": "object",
         "properties": {
          "code": {
           "type": "string"
          },
          "severity": {
           "type": "string",
           "enum": [
            "rejection",
            "notification"
           ]
          }
         }
        }
       }
      }
     },
     "delivery": {
      "type": "object",
      "properties": {
       "pdf": {
        "type": "boolean"
       },
       "zip": {
        "type": "boolean"
       },
       "email": {
        "type": "object",
        "properties": {
         "status": {
          "type": "string",
          "enum": [
           "pending",
           "sent",
           "failed",
           "skipped",
           "bounced",
           "complained"
          ]
         }
        }
       }
      }
     },
     "error": {
      "type": "object",
      "description": "Solo en `….error`. El texto es fijo por código: nunca el mensaje de la DIAN.",
      "properties": {
       "code": {
        "type": "string"
       },
       "message": {
        "type": "string"
       }
      }
     }
    }
   },
   "BalanceEventData": {
    "type": "object",
    "description": "`balance.low` (solo producción): el saldo de la cuenta quedó bajo o se agotó. Lleva solo el nivel: el saldo es de la cuenta y lo comparten todas sus empresas.",
    "properties": {
     "object": {
      "type": "string",
      "enum": [
       "balance"
      ]
     },
     "level": {
      "type": "string",
      "enum": [
       "low",
       "depleted"
      ]
     }
    }
   },
   "NumberingLowEventData": {
    "type": "object",
    "description": "`numbering.low` (solo producción): a la resolución le quedan pocos números (10 % del rango, y otra vez con 10 números).",
    "properties": {
     "object": {
      "type": "string",
      "enum": [
       "numbering"
      ]
     },
     "document": {
      "type": "string",
      "enum": [
       "invoice",
       "support_document",
       "equivalent_document"
      ],
      "description": "De qué documento es la numeración (la fase 3 avisa también del documento soporte y del POS)."
     },
     "prefix": {
      "type": [
       "string",
       "null"
      ]
     },
     "resolution_number": {
      "type": "string"
     },
     "remaining": {
      "type": "integer"
     },
     "to": {
      "type": "integer"
     }
    }
   },
   "NumberingExpiringEventData": {
    "type": "object",
    "description": "`numbering.expiring` (solo producción): la resolución vence en 30 y en 7 días.",
    "properties": {
     "object": {
      "type": "string",
      "enum": [
       "numbering"
      ]
     },
     "document": {
      "type": "string",
      "enum": [
       "invoice",
       "support_document",
       "equivalent_document"
      ],
      "description": "De qué documento es la numeración (la fase 3 avisa también del documento soporte y del POS)."
     },
     "prefix": {
      "type": [
       "string",
       "null"
      ]
     },
     "resolution_number": {
      "type": "string"
     },
     "valid_to": {
      "type": "string",
      "format": "date"
     },
     "days_left": {
      "type": "integer"
     }
    }
   },
   "CertificateEventData": {
    "type": "object",
    "description": "`certificate.expiring` (los dos ambientes): el certificado de firma vence en 30, 15, 7 y 1 día.",
    "properties": {
     "object": {
      "type": "string",
      "enum": [
       "certificate"
      ]
     },
     "expires_on": {
      "type": "string",
      "format": "date"
     },
     "days_left": {
      "type": "integer"
     }
    }
   },
   "TestEventData": {
    "type": "object",
    "description": "`webhook.test`: lo manda «Probar» (app) o POST …/test, solo a ese endpoint.",
    "properties": {
     "object": {
      "type": "string",
      "enum": [
       "test"
      ]
     },
     "message": {
      "type": "string"
     }
    }
   },
   "SupportDocumentEventData": {
    "type": "object",
    "description": "Resumen de un documento soporte o de su nota de ajuste (nunca datos del proveedor ni líneas). Pide el documento completo con GET /v1/{support_documents|support_document_adjustments}/{id}.",
    "required": [
     "object",
     "id",
     "status",
     "environment",
     "dian"
    ],
    "properties": {
     "status": {
      "type": "string",
      "enum": [
       "pending",
       "sending",
       "accepted",
       "rejected",
       "error",
       "contingency"
      ],
      "description": "Nunca `processing`: ese estado solo existe en las respuestas de la API."
     },
     "environment": {
      "type": "string",
      "enum": [
       "test",
       "live"
      ]
     },
     "number": {
      "type": [
       "string",
       "null"
      ]
     },
     "prefix": {
      "type": [
       "string",
       "null"
      ]
     },
     "external_id": {
      "type": [
       "string",
       "null"
      ],
      "description": "Tu identificador, solo en los documentos creados por la API."
     },
     "origin": {
      "type": "string",
      "enum": [
       "api",
       "app",
       "contapyme"
      ]
     },
     "issued_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "total": {
      "type": [
       "string",
       "null"
      ],
      "description": "Texto decimal con dos decimales."
     },
     "dian": {
      "type": "object",
      "properties": {
       "status_code": {
        "type": [
         "string",
         "null"
        ]
       },
       "rules": {
        "type": "array",
        "maxItems": 20,
        "description": "Los códigos de las reglas de la DIAN, con las de rechazo primero.",
        "items": {
         "type": "object",
         "properties": {
          "code": {
           "type": "string"
          },
          "severity": {
           "type": "string",
           "enum": [
            "rejection",
            "notification"
           ]
          }
         }
        }
       }
      }
     },
     "error": {
      "type": "object",
      "description": "Solo en `….error`. El texto es fijo por código: nunca el mensaje de la DIAN.",
      "properties": {
       "code": {
        "type": "string"
       },
       "message": {
        "type": "string"
       }
      }
     },
     "object": {
      "type": "string",
      "enum": [
       "support_document",
       "support_document_adjustment"
      ]
     },
     "id": {
      "type": "string",
      "description": "sd_… | sda_…"
     },
     "cuds": {
      "type": [
       "string",
       "null"
      ],
      "description": "Código único del documento soporte."
     },
     "support_document": {
      "type": "object",
      "description": "En la nota de ajuste: el documento soporte que ajusta.",
      "properties": {
       "id": {
        "type": "string",
        "pattern": "^sd_[0-9a-f]{32}$"
       }
      }
     },
     "delivery": {
      "type": "null",
      "description": "El documento soporte no se expide al vendedor: no hay PDF ni correo."
     }
    }
   },
   "EquivalentDocumentEventData": {
    "type": "object",
    "description": "Resumen de un documento equivalente electrónico o de su nota de ajuste (nunca datos del comprador ni líneas). Pide el documento completo con GET /v1/{equivalent_documents|equivalent_document_adjustments}/{id}.",
    "required": [
     "object",
     "id",
     "status",
     "environment",
     "dian",
     "delivery"
    ],
    "properties": {
     "status": {
      "type": "string",
      "enum": [
       "pending",
       "sending",
       "accepted",
       "rejected",
       "error",
       "contingency"
      ],
      "description": "Nunca `processing`: ese estado solo existe en las respuestas de la API."
     },
     "environment": {
      "type": "string",
      "enum": [
       "test",
       "live"
      ]
     },
     "number": {
      "type": [
       "string",
       "null"
      ]
     },
     "prefix": {
      "type": [
       "string",
       "null"
      ]
     },
     "external_id": {
      "type": [
       "string",
       "null"
      ],
      "description": "Tu identificador, solo en los documentos creados por la API."
     },
     "origin": {
      "type": "string",
      "enum": [
       "api",
       "app",
       "contapyme"
      ]
     },
     "issued_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "total": {
      "type": [
       "string",
       "null"
      ],
      "description": "Texto decimal con dos decimales."
     },
     "dian": {
      "type": "object",
      "properties": {
       "status_code": {
        "type": [
         "string",
         "null"
        ]
       },
       "rules": {
        "type": "array",
        "maxItems": 20,
        "description": "Los códigos de las reglas de la DIAN, con las de rechazo primero.",
        "items": {
         "type": "object",
         "properties": {
          "code": {
           "type": "string"
          },
          "severity": {
           "type": "string",
           "enum": [
            "rejection",
            "notification"
           ]
          }
         }
        }
       }
      }
     },
     "error": {
      "type": "object",
      "description": "Solo en `….error`. El texto es fijo por código: nunca el mensaje de la DIAN.",
      "properties": {
       "code": {
        "type": "string"
       },
       "message": {
        "type": "string"
       }
      }
     },
     "object": {
      "type": "string",
      "enum": [
       "equivalent_document",
       "equivalent_document_adjustment"
      ]
     },
     "id": {
      "type": "string",
      "description": "pos_… | posa_…"
     },
     "cude": {
      "type": [
       "string",
       "null"
      ],
      "description": "Código único del documento."
     },
     "document_type": {
      "type": "string",
      "description": "El tipo de documento equivalente (20 POS, 25, 27, 30…). Solo en `equivalent_document`."
     },
     "equivalent_document": {
      "type": "object",
      "description": "En la nota de ajuste: el documento equivalente que ajusta.",
      "properties": {
       "id": {
        "type": "string",
        "pattern": "^pos_[0-9a-f]{32}$"
       }
      }
     },
     "delivery": {
      "type": "object",
      "properties": {
       "pdf": {
        "type": "boolean"
       },
       "zip": {
        "type": "boolean"
       },
       "email": {
        "type": "object",
        "properties": {
         "status": {
          "type": "string",
          "enum": [
           "pending",
           "sent",
           "failed",
           "skipped",
           "bounced",
           "complained"
          ]
         }
        }
       }
      }
     }
    }
   },
   "PayrollEventData": {
    "type": "object",
    "description": "Resumen de una nómina electrónica (102) o de su nota de ajuste (103): SIN el trabajador (ni su documento, nombre o salario) y SIN montos. Pide el documento completo con GET /v1/{payrolls|payroll_adjustments}/{id}.",
    "required": [
     "object",
     "id",
     "status",
     "environment",
     "dian"
    ],
    "properties": {
     "object": {
      "type": "string",
      "enum": [
       "payroll",
       "payroll_adjustment"
      ]
     },
     "id": {
      "type": "string",
      "description": "pr_… | pra_…"
     },
     "status": {
      "type": "string",
      "enum": [
       "pending",
       "sending",
       "validating",
       "accepted",
       "rejected",
       "error"
      ]
     },
     "environment": {
      "type": "string",
      "enum": [
       "test",
       "live"
      ]
     },
     "number": {
      "type": [
       "string",
       "null"
      ]
     },
     "prefix": {
      "type": [
       "string",
       "null"
      ]
     },
     "external_id": {
      "type": [
       "string",
       "null"
      ]
     },
     "origin": {
      "type": "string",
      "enum": [
       "api",
       "app"
      ]
     },
     "cune": {
      "type": [
       "string",
       "null"
      ]
     },
     "issued_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "type": {
      "type": [
       "string",
       "null"
      ],
      "enum": [
       "replace",
       "delete",
       null
      ],
      "description": "Solo en la nota de ajuste."
     },
     "predecessor": {
      "type": [
       "object",
       "null"
      ],
      "properties": {
       "id": {
        "type": "string"
       }
      }
     },
     "submission": {
      "type": [
       "string",
       "null"
      ],
      "enum": [
       "sync",
       "test_set",
       null
      ]
     },
     "dian": {
      "type": "object",
      "properties": {
       "status_code": {
        "type": [
         "string",
         "null"
        ]
       },
       "rules": {
        "type": "array",
        "maxItems": 20,
        "description": "Los códigos de las reglas de la DIAN, con las de rechazo primero.",
        "items": {
         "type": "object",
         "properties": {
          "code": {
           "type": "string"
          },
          "severity": {
           "type": "string",
           "enum": [
            "rejection",
            "notification"
           ]
          }
         }
        }
       }
      }
     },
     "error": {
      "type": "object",
      "description": "Solo en `….error`. Texto fijo por código.",
      "properties": {
       "code": {
        "type": "string"
       },
       "message": {
        "type": "string"
       }
      }
     }
    }
   },
   "RadianEventData": {
    "type": "object",
    "description": "Resumen de un evento RADIAN (030–034): sin nombres ni NIT del emisor de la factura. Pide el evento completo con GET /v1/radian_events/{id}.",
    "required": [
     "object",
     "id",
     "status",
     "environment",
     "event_code",
     "dian"
    ],
    "properties": {
     "object": {
      "type": "string",
      "enum": [
       "radian_event"
      ]
     },
     "id": {
      "type": "string",
      "pattern": "^rev_[0-9a-f]{32}$"
     },
     "status": {
      "type": "string",
      "enum": [
       "pending",
       "sending",
       "validating",
       "accepted",
       "rejected",
       "error"
      ]
     },
     "environment": {
      "type": "string",
      "enum": [
       "test",
       "live"
      ]
     },
     "event_code": {
      "type": "string",
      "enum": [
       "030",
       "031",
       "032",
       "033",
       "034"
      ]
     },
     "number": {
      "type": [
       "string",
       "null"
      ]
     },
     "prefix": {
      "type": [
       "string",
       "null"
      ]
     },
     "external_id": {
      "type": [
       "string",
       "null"
      ]
     },
     "origin": {
      "type": "string",
      "enum": [
       "api",
       "app"
      ]
     },
     "cude": {
      "type": [
       "string",
       "null"
      ]
     },
     "issued_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "invoice": {
      "type": "object",
      "properties": {
       "cufe": {
        "type": [
         "string",
         "null"
        ]
       },
       "number": {
        "type": [
         "string",
         "null"
        ]
       },
       "id": {
        "type": [
         "string",
         "null"
        ]
       }
      }
     },
     "dian": {
      "type": "object",
      "properties": {
       "status_code": {
        "type": [
         "string",
         "null"
        ]
       },
       "rules": {
        "type": "array",
        "maxItems": 20,
        "description": "Los códigos de las reglas de la DIAN, con las de rechazo primero.",
        "items": {
         "type": "object",
         "properties": {
          "code": {
           "type": "string"
          },
          "severity": {
           "type": "string",
           "enum": [
            "rejection",
            "notification"
           ]
          }
         }
        }
       }
      }
     },
     "error": {
      "type": "object",
      "description": "Solo en `….error`. Texto fijo por código.",
      "properties": {
       "code": {
        "type": "string"
       },
       "message": {
        "type": "string"
       }
      }
     }
    }
   },
   "WebhookDelivery": {
    "type": "object",
    "description": "Un evento hacia un endpoint, con sus reintentos (8 automáticos en unas 32 horas; 3 si es manual).",
    "required": [
     "id",
     "object",
     "endpoint_id",
     "event_id",
     "status",
     "attempts"
    ],
    "properties": {
     "id": {
      "type": "string",
      "pattern": "^del_[0-9a-f]{32}$"
     },
     "object": {
      "type": "string",
      "enum": [
       "webhook_delivery"
      ]
     },
     "endpoint_id": {
      "type": "string"
     },
     "event_id": {
      "type": "string"
     },
     "event_type": {
      "type": [
       "string",
       "null"
      ]
     },
     "status": {
      "type": "string",
      "enum": [
       "pending",
       "sending",
       "succeeded",
       "failed",
       "canceled"
      ]
     },
     "attempts": {
      "type": "integer"
     },
     "manual": {
      "type": "boolean"
     },
     "next_attempt_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "last_attempt": {
      "type": [
       "object",
       "null"
      ],
      "properties": {
       "at": {
        "type": [
         "string",
         "null"
        ],
        "format": "date-time"
       },
       "status_code": {
        "type": [
         "integer",
         "null"
        ]
       },
       "error": {
        "type": [
         "string",
         "null"
        ],
        "enum": [
         "http_3xx",
         "http_4xx",
         "http_5xx",
         "http_other",
         "timeout",
         "connection",
         "tls",
         "dns",
         "blocked_address",
         "invalid_url",
         "secret_unavailable",
         "interrupted",
         "unknown",
         null
        ]
       },
       "duration_ms": {
        "type": [
         "integer",
         "null"
        ]
       }
      }
     },
     "created_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "succeeded_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     }
    }
   },
   "Balance": {
    "type": "object",
    "description": "El saldo prepago de Trevol. Es de la **cuenta**, no de la empresa: todas las empresas de la cuenta lo comparten (`shared: true`) y cualquier llave de cualquiera de ellas, de lectura o de escritura, `test` o `live`, ve el mismo. Solo lo que se emite en producción (llaves `live`) lo consume; la habilitación (`test`) no cobra. `available` es lo que se puede gastar (en pesos); `held`, lo apartado por documentos que la DIAN todavía valida; `overdraft`, cuánto puede bajar `available` de cero al apartar un documento; `low_threshold`, el umbral del aviso de saldo bajo (el 20 % de la última recarga; `null` sin recargas). `level`: `empty` con `available` ≤ 0, `low` por debajo de `low_threshold`, si no `ok`. Con `available` por debajo del precio de un documento, emitir en producción responde 402 `insufficient_balance`. El evento `balance.low` avisa por webhook.",
    "required": [
     "object",
     "currency",
     "available",
     "held",
     "overdraft",
     "low_threshold",
     "level",
     "updated_at",
     "shared"
    ],
    "properties": {
     "object": {
      "type": "string",
      "enum": [
       "balance"
      ]
     },
     "currency": {
      "type": "string",
      "enum": [
       "COP"
      ]
     },
     "available": {
      "type": "integer",
      "description": "Lo que se puede gastar, en pesos (puede ser negativo)."
     },
     "held": {
      "type": "integer",
      "description": "Apartado por documentos que la DIAN todavía valida."
     },
     "overdraft": {
      "type": "integer",
      "description": "Cuánto puede bajar `available` de cero al apartar un documento."
     },
     "low_threshold": {
      "type": [
       "integer",
       "null"
      ],
      "description": "El umbral del aviso de saldo bajo; null sin recargas."
     },
     "level": {
      "type": "string",
      "enum": [
       "ok",
       "low",
       "empty"
      ]
     },
     "updated_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time",
      "description": "Cuándo cambió el saldo por última vez; null si nunca tuvo."
     },
     "shared": {
      "type": "boolean",
      "enum": [
       true
      ],
      "description": "Siempre true: el saldo es de la cuenta y lo comparten todas sus empresas."
     }
    }
   },
   "BalanceTransaction": {
    "type": "object",
    "description": "Un movimiento del saldo de la cuenta (un documento es una sola fila).",
    "required": [
     "id",
     "object",
     "type",
     "status",
     "amount",
     "available_after",
     "description",
     "document",
     "company",
     "created_at"
    ],
    "properties": {
     "id": {
      "type": "string",
      "pattern": "^btx_[0-9]{1,18}$",
      "description": "Úsalo en `starting_after` para pedir la página siguiente."
     },
     "object": {
      "type": "string",
      "enum": [
       "balance_transaction"
      ]
     },
     "type": {
      "type": "string",
      "enum": [
       "document",
       "top_up",
       "bonus",
       "adjustment",
       "top_up_reversal",
       "license_fee",
       "expiration",
       "other"
      ]
     },
     "status": {
      "type": "string",
      "enum": [
       "charged",
       "pending",
       "released",
       "completed"
      ],
      "description": "De un documento: pending, charged o released. Lo demás: completed."
     },
     "amount": {
      "type": "integer",
      "description": "Lo que hizo con el disponible, en pesos y con signo (released: 0)."
     },
     "available_after": {
      "type": [
       "integer",
       "null"
      ],
      "description": "El disponible justo después."
     },
     "description": {
      "type": "string",
      "description": "En español, como en la app."
     },
     "document": {
      "type": [
       "object",
       "null"
      ],
      "description": "Solo en `type: document`.",
      "properties": {
       "type": {
        "type": [
         "string",
         "null"
        ],
        "enum": [
         "invoice",
         "credit_note",
         "debit_note",
         "support_document",
         "support_document_adjustment",
         "equivalent_document",
         "equivalent_document_adjustment",
         "payroll",
         "payroll_adjustment",
         "radian_event",
         null
        ]
       },
       "number": {
        "type": [
         "string",
         "null"
        ]
       }
      }
     },
     "company": {
      "type": [
       "object",
       "null"
      ],
      "description": "La empresa de la cuenta que emitió el documento.",
      "properties": {
       "nit": {
        "type": [
         "string",
         "null"
        ]
       },
       "name": {
        "type": [
         "string",
         "null"
        ]
       }
      }
     },
     "reference": {
      "type": [
       "string",
       "null"
      ],
      "description": "La referencia TRV-REC-… de una recarga o de su reverso."
     },
     "created_at": {
      "type": "string",
      "format": "date-time"
     }
    }
   },
   "TopUpBuyer": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "document_type": {
      "type": "string",
      "enum": [
       "13",
       "31",
       "22",
       "41"
      ],
      "description": "13 cédula, 31 NIT, 22 cédula de extranjería, 41 pasaporte (lo que acepta la facturación de la recarga)."
     },
     "document_number": {
      "type": "string",
      "description": "Sin DV ni puntos (con 13 y 31, solo dígitos)."
     },
     "check_digit": {
      "type": [
       "string",
       "integer"
      ],
      "description": "Con NIT, obligatorio: el DV del NIT. No va con los demás."
     },
     "person_type": {
      "type": "string",
      "enum": [
       "legal",
       "natural"
      ],
      "description": "legal (persona jurídica, solo con NIT) o natural."
     },
     "name": {
      "type": "string",
      "maxLength": 450,
      "description": "Razón social o, para una persona natural, nombres y apellidos (al menos dos palabras)."
     },
     "email": {
      "type": "string",
      "maxLength": 254,
      "description": "A dónde llega la factura de la recarga."
     },
     "phone": {
      "type": "string",
      "maxLength": 50
     },
     "address": {
      "type": "string",
      "maxLength": 300
     },
     "municipality_code": {
      "type": "string",
      "pattern": "^[0-9]{5}$",
      "description": "Código DANE del municipio (5 dígitos)."
     }
    },
    "required": [
     "document_type",
     "document_number",
     "person_type",
     "name",
     "email"
    ],
    "description": "El comprador de la factura de la recarga. Sin él, la empresa de la llave."
   },
   "TopUpInput": {
    "type": "object",
    "additionalProperties": false,
    "required": [
     "amount_cop"
    ],
    "properties": {
     "amount_cop": {
      "type": "integer",
      "minimum": 1,
      "description": "En pesos, entre la recarga mínima y la máxima."
     },
     "buyer": {
      "$ref": "#/components/schemas/TopUpBuyer"
     }
    }
   },
   "TopUp": {
    "type": "object",
    "required": [
     "object",
     "reference",
     "amount_cop",
     "status",
     "wompi"
    ],
    "properties": {
     "object": {
      "type": "string",
      "enum": [
       "top_up"
      ]
     },
     "reference": {
      "type": "string",
      "pattern": "^TRV-REC-"
     },
     "amount_cop": {
      "type": "integer"
     },
     "status": {
      "type": "string",
      "enum": [
       "prepared"
      ]
     },
     "wompi": {
      "type": "object",
      "description": "Lo que necesita el widget de Wompi (WidgetCheckout).",
      "required": [
       "public_key",
       "reference",
       "amount_in_cents",
       "currency",
       "signature",
       "expiration_time"
      ],
      "properties": {
       "public_key": {
        "type": "string"
       },
       "reference": {
        "type": "string"
       },
       "amount_in_cents": {
        "type": "integer"
       },
       "currency": {
        "type": "string",
        "enum": [
         "COP"
        ]
       },
       "signature": {
        "type": "string",
        "pattern": "^[0-9a-f]{64}$",
        "description": "La firma de integridad (`signature: {integrity}` del widget)."
       },
       "expiration_time": {
        "type": "string",
        "format": "date-time",
        "description": "Una hora después de preparar (UTC)."
       }
      }
     }
    }
   },
   "Problem": {
    "type": "object",
    "required": [
     "type",
     "title",
     "status",
     "code",
     "retryable"
    ],
    "properties": {
     "type": {
      "type": "string",
      "format": "uri"
     },
     "title": {
      "type": "string"
     },
     "status": {
      "type": "integer"
     },
     "code": {
      "type": "string",
      "enum": [
       "authentication_required",
       "certificate_problem",
       "company_not_enabled",
       "dian_rejected",
       "dian_unavailable",
       "duplicate_document",
       "external_id_in_use",
       "file_unavailable",
       "idempotency_key_required",
       "idempotency_key_reused",
       "insufficient_balance",
       "internal_error",
       "invalid_api_key",
       "invalid_json",
       "invalid_request",
       "invalid_state",
       "method_not_allowed",
       "not_found",
       "numbering_unavailable",
       "permission_denied",
       "previous_event_pending",
       "rate_limited",
       "request_in_progress",
       "tacit_acceptance_not_due",
       "top_up_above_maximum",
       "top_up_below_minimum",
       "top_ups_unavailable",
       "unsupported_version",
       "validation_error",
       "webhook_limit_reached"
      ]
     },
     "detail": {
      "type": "string"
     },
     "retryable": {
      "type": "boolean"
     },
     "retry_after": {
      "type": "integer"
     },
     "request_id": {
      "type": "string"
     },
     "errors": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "field": {
         "type": "string"
        },
        "pointer": {
         "type": "string"
        },
        "message": {
         "type": "string"
        }
       }
      }
     },
     "document": {
      "$ref": "#/components/schemas/Document"
     },
     "existing_id": {
      "type": "string",
      "description": "En `external_id_in_use` y `duplicate_document`: el id (con el prefijo de su clase) del recurso que ya existe."
     },
     "reason": {
      "type": "string",
      "enum": [
       "missing_legal_representative",
       "missing_pin",
       "missing_software",
       "missing_technical_key",
       "no_resolution",
       "payroll_not_enabled",
       "prefix_in_use",
       "resolution_exhausted",
       "resolution_expired",
       "resolution_not_yet_valid"
      ],
      "description": "En `company_not_enabled` (`missing_legal_representative`, `missing_pin`, `missing_software`, `payroll_not_enabled`) y en `numbering_unavailable` (`missing_technical_key`, `no_resolution`, `prefix_in_use`, `resolution_exhausted`, `resolution_expired`, `resolution_not_yet_valid`): por qué."
     },
     "previous": {
      "type": "string",
      "description": "En `previous_event_pending`: el evento que la DIAN todavía no muestra."
     },
     "minimum_cop": {
      "type": [
       "integer",
       "null"
      ],
      "description": "En `top_up_below_minimum`: la recarga mínima, en pesos."
     },
     "maximum_cop": {
      "type": [
       "integer",
       "null"
      ],
      "description": "En `top_up_above_maximum`: la recarga máxima, en pesos."
     },
     "limit": {
      "type": "string",
      "description": "En `rate_limited`: qué límite se pasó."
     },
     "available_from": {
      "type": [
       "string",
       "null"
      ],
      "format": "date",
      "description": "En `tacit_acceptance_not_due`: desde cuándo procede la aceptación tácita. `null` si la DIAN todavía no muestra el recibo del bien (032) de la compradora: consulta de nuevo en unos minutos con `GET /v1/invoices/{id}/tacit_acceptance`."
     },
     "rules": {
      "type": "array",
      "items": {
       "type": "object"
      },
      "description": "En `tacit_acceptance_not_due`: las reglas (LGC…) que la DIAN aplicaría; las locales llevan `local: true`."
     }
    }
   }
  }
 }
}