{ "openapi": "3.0.0", "info": { "title": "MATIAS API — Facturación Electrónica DIAN (UBL 2.1)", "description": "API RESTful para la generación, gestión y consulta de documentos electrónicos en Colombia. Integración completa con DIAN, soporte para facturas, notas crédito, notas débito, documentos soporte y nómina electrónica. Compatible con UBL 2.1.", "termsOfService": "https://matias-api.com/terminos/", "contact": { "name": "Soporte Técnico MATIAS", "url": "https://matias-api.com/#contact", "email": "soporte@matias.com.co" }, "license": { "name": "Licencia Propietaria", "url": "https://matias-api.com/" }, "version": "3.2.0", "x-docs": "https://docs.matias-api.com/llms.txt" }, "servers": [ { "url": "https://sandbox-api.matias-api.com", "description": "Sandbox (gratuito, certificados de prueba, no se envía nada a la DIAN)" }, { "url": "{productionUrl}", "description": "Producción: URL base entregada al contratar el servicio", "variables": { "productionUrl": { "default": "https://sandbox-api.matias-api.com", "description": "Reemplázala por la URL de producción de tu contrato" } } } ], "paths": { "/api/ubl2.1/acquirer": { "get": { "tags": [ "Consultas" ], "summary": "Consultar adquiriente en la DIAN y buscar el cliente asociado", "description": "Consulta el servicio SOAP GetAcquirer de la DIAN por tipo y número de identificación, y adicionalmente busca en la base de datos local un cliente (`customers`) que coincida con ese número de identificación (`dni`).", "operationId": "b01597f09a446aed79b22387cab7231a", "parameters": [ { "name": "identificationType", "in": "query", "description": "Tipo de identificación DIAN (numérico)", "required": true, "schema": { "type": "integer" } }, { "name": "identificationNumber", "in": "query", "description": "Número de identificación del adquiriente a consultar", "required": true, "schema": { "type": "string" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Información del adquiriente obtenida exitosamente", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Consulta generada con éxito" }, "content": { "description": "Resultado crudo de GetAcquirerResult devuelto por la DIAN", "type": "object" }, "customer": { "description": "Cliente local coincidente por número de identificación (dni), o null si no existe", "type": "object", "nullable": true } }, "type": "object" } } } }, "401": { "description": "No autenticado" }, "403": { "description": "error_code NOT_AVAILABLE_IN_SANDBOX: no disponible en sandbox (requiere el certificado real). how_to_proceed indica cómo enviar los datos del cliente en el documento" }, "422": { "description": "Parámetros de identificación inválidos o faltantes" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/bulk/documents": { "get": { "tags": [ "Envío Masivo (Bulk)" ], "summary": "Listar lotes de la compañía", "description": "Lista paginada de todos los lotes de envío masivo de la compañía actual, ordenados del más reciente al más antiguo.", "operationId": "bulkDocumentsIndex", "parameters": [ { "name": "status", "in": "query", "description": "Filtrar por estado del lote", "required": false, "schema": { "type": "string", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "PARTIAL", "FAILED" ] } }, { "name": "per_page", "in": "query", "description": "Lotes por página", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "page", "in": "query", "description": "Número de página", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "current_page": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BulkBatchResponse" } }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "last_page": { "type": "integer" }, "next_page_url": { "type": "string", "nullable": true } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Envío Masivo (Bulk)" ], "summary": "Crear lote de documentos para procesamiento asíncrono", "description": "Acepta un lote de documentos electrónicos para procesamiento en cola. Retorna 201 Created inmediatamente con batch_id para polling posterior. Soporta idempotencia mediante header Idempotency-Key. Envíe Accept: application/json para recibir todos los errores en JSON.", "operationId": "bulkDocumentsStore", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "UUID v4 para idempotencia (máximo 36 caracteres; una key más larga responde 422). Si se reenvía el mismo key con el mismo payload, retorna el lote original sin reprocesar (201); con un payload distinto responde 409. Válido por 24 horas.", "required": false, "schema": { "type": "string", "format": "uuid", "maxLength": 36 } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "description": "Lote de documentos a procesar", "required": true, "content": { "application/json": { "schema": { "required": [ "mode", "documents" ], "properties": { "mode": { "description": "Modo de consecutivo. auto-increment: el sistema asigna número automáticamente. manual: cada documento trae su propio número.", "type": "string", "enum": [ "auto-increment", "manual" ], "example": "auto-increment" }, "stop_on_error": { "description": "Si true, el primer documento que no termine en SUCCESS (FAILED, REJECTED_BY_DIAN o POSSIBLY_SENT) cancela los items que siguen en cola (CANCELLED).", "type": "boolean", "example": false }, "default_resolution_number": { "description": "Número de resolución por defecto. Se inyecta en documentos cuyo payload no lo incluya.", "type": "string", "maxLength": 50, "example": "18764002566734" }, "default_prefix": { "description": "Prefijo por defecto. Se inyecta en documentos cuyo payload no lo incluya.", "type": "string", "maxLength": 10, "example": "SETT" }, "documents": { "description": "Array de documentos a procesar. Máximo según plan (FREE=5, Pago=50, Ilimitado=200; si se supera responde 422).", "type": "array", "items": { "$ref": "#/components/schemas/BulkDocumentItem" }, "maxItems": 200, "minItems": 1 } }, "type": "object" } } } }, "responses": { "201": { "description": "Lote aceptado para procesamiento asíncrono (también en un replay idempotente, con el lote original)", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "batch_id": { "type": "string", "format": "uuid", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, "received": { "type": "integer", "example": 2 }, "accepted": { "type": "integer", "example": 2 }, "rejected": { "type": "integer", "example": 0 }, "status": { "type": "string", "example": "PENDING" }, "status_url": { "type": "string", "example": "/api/ubl2.1/bulk/documents/f47ac10b-58cc-4372-a567-0e02b2c3d479" }, "items": { "type": "array", "items": { "properties": { "index": { "type": "integer" }, "client_reference": { "type": "string", "nullable": true }, "item_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "example": "QUEUED" } }, "type": "object" } }, "estimated_completion_seconds": { "type": "integer", "example": 12 } }, "type": "object" } } } }, "402": { "description": "Membresía sin cupo, o cuota insuficiente para el lote completo (descuenta los documentos pendientes de lotes anteriores). En el control inicial trae {success:false, message[, requested]}; si la cuota se agota al admitir el lote, trae solo {message}.", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Cuota insuficiente para procesar el lote completo." }, "requested": { "type": "integer", "example": 25 } }, "type": "object" } } } }, "409": { "description": "Idempotency-Key reutilizado con payload distinto. Solo trae {message}.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Idempotency-Key reutilizado con payload distinto." } }, "type": "object" } } } }, "413": { "description": "El lote excede el máximo permitido para la suscripción (se valida antes que el esquema)", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "El lote excede el máximo permitido para tu suscripción." }, "max_items": { "type": "integer", "example": 50 }, "received": { "type": "integer", "example": 75 }, "upgrade_url": { "type": "string", "example": "https://api.example.com/upgrade" } }, "type": "object" } } } }, "422": { "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "El UUID del documento está repetido dentro del lote." }, "errors": { "type": "object", "nullable": true } }, "type": "object" } } } }, "429": { "description": "Tres causas: (1) rate limit por minuto, contado por usuario y por empresa (varios usuarios de la empresa comparten el cupo); en FREE responde {success:false, message, upgrade_url} sin Retry-After. (2) La empresa superaría el máximo de documentos en proceso (QUEUED/PROCESSING). (3) Otro lote de la misma empresa está en admisión. En (2) y (3) solo trae {message}. Reintente tras Retry-After con el mismo Idempotency-Key.", "headers": { "Retry-After": { "description": "Segundos a esperar antes de reintentar (ausente en el 429 del plan FREE)", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "La empresa ya tiene 980 documentos en proceso y el máximo simultáneo es 1000. Reintente más tarde." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/bulk/documents/{batchId}": { "get": { "tags": [ "Envío Masivo (Bulk)" ], "summary": "Consultar estado completo de un lote", "description": "Retorna el estado detallado del lote con resumen de cada item. Incluye contadores de éxito/fallo y timestamps.", "operationId": "bulkDocumentsShow", "parameters": [ { "name": "batchId", "in": "path", "description": "UUID del lote (retornado en el POST)", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Estado del lote con items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkBatchResponse" } } } }, "404": { "description": "Lote no encontrado o no pertenece a la compañía" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/bulk/documents/{batchId}/items": { "get": { "tags": [ "Envío Masivo (Bulk)" ], "summary": "Listar items de un lote con filtros", "description": "Lista paginada de los items de un lote, con filtros opcionales por estado y tipo de documento.", "operationId": "bulkDocumentsItems", "parameters": [ { "name": "batchId", "in": "path", "description": "UUID del lote", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "Filtrar por estado del item", "required": false, "schema": { "type": "string", "enum": [ "QUEUED", "PROCESSING", "SUCCESS", "FAILED", "REJECTED_BY_DIAN", "POSSIBLY_SENT", "CANCELLED" ] } }, { "name": "kind", "in": "query", "description": "Filtrar por tipo de documento", "required": false, "schema": { "type": "string", "enum": [ "invoice", "credit_note", "debit_note", "support_document", "adjustment_note", "pos_document" ] } }, { "name": "per_page", "in": "query", "description": "Items por página", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 200, "minimum": 1 } }, { "name": "page", "in": "query", "description": "Número de página", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "current_page": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BulkBatchItemResponse" } }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "last_page": { "type": "integer" }, "next_page_url": { "type": "string", "nullable": true } }, "type": "object" } } } }, "404": { "description": "Lote no encontrado" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/document/run-test": { "post": { "tags": [ "Documentos Electrónicos" ], "summary": "Ejecutar prueba de documento electrónico", "operationId": "3bebb021d1ed5b2145cf6daca49733d0", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "test_data": { "description": "Datos de prueba del documento", "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Prueba ejecutada correctamente" }, "422": { "description": "Error de validación" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/auto-increment/invoices/{uuid}": { "patch": { "tags": [ "Documentos con Consecutivo Automático" ], "summary": "Reenviar factura rechazada por la DIAN", "operationId": "1557dacad5de88263f01c307f9a66b55", "parameters": [ { "name": "uuid", "in": "path", "description": "UUID del envío fallido", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "description": "Datos corregidos del documento", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceRequest" } } } }, "responses": { "200": { "description": "Documento reenviado exitosamente" }, "404": { "description": "Documento no encontrado" }, "422": { "description": "Error de validación" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/auto-increment/support-documents/{uuid}": { "patch": { "tags": [ "Documentos con Consecutivo Automático" ], "summary": "Reenviar documento soporte rechazado", "operationId": "af286c0ff67b4e650aff8b7d16d8dd6f", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceRequest" } } } }, "responses": { "200": { "description": "Documento reenviado" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/auto-increment/credit-notes/{uuid}": { "patch": { "tags": [ "Documentos con Consecutivo Automático" ], "summary": "Reenviar nota crédito rechazada", "operationId": "51f571e7ec16c7df667ed14f575121fb", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceRequest" } } } }, "responses": { "200": { "description": "Nota crédito reenviada" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/auto-increment/debit-notes/{uuid}": { "patch": { "tags": [ "Documentos con Consecutivo Automático" ], "summary": "Reenviar nota débito rechazada", "operationId": "e88a4696e5eab658df988a3f6666dbdd", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceRequest" } } } }, "responses": { "200": { "description": "Nota débito reenviada" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/auto-increment/adjustment-notes/{uuid}": { "patch": { "tags": [ "Documentos con Consecutivo Automático" ], "summary": "Reenviar nota de ajuste rechazada", "operationId": "87ca3a28c8e2120aede90c3dc048041c", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceRequest" } } } }, "responses": { "200": { "description": "Nota de ajuste reenviada" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/auto-increment/pos-documents/{uuid}": { "patch": { "tags": [ "Documentos con Consecutivo Automático" ], "summary": "Reenviar documento POS rechazado", "operationId": "1a78f4729c1064f3994fae22ecd516be", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceRequest" } } } }, "responses": { "200": { "description": "Documento POS reenviado" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/auto-increment/invoices": { "post": { "tags": [ "Documentos con Consecutivo Automático" ], "summary": "Crear una Factura Electrónica con consecutivo automático", "operationId": "ddb5d03f6d4af6eba7abe2e150d2aa56", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "description": "Datos de la factura a crear. El campo `document_number` debe ser omitido.", "required": true, "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/InvoiceRequest" }, { "properties": { "attachments": { "$ref": "#/components/schemas/UserAttachments" } }, "type": "object" } ] } } } }, "responses": { "200": { "description": "Documento procesado exitosamente" }, "402": { "description": "Límite de membresía alcanzado" }, "422": { "description": "Error de validación de datos" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/auto-increment/support-documents": { "post": { "tags": [ "Documentos con Consecutivo Automático" ], "summary": "Crear Documento Soporte con consecutivo automático", "operationId": "778d68d101420792236e1254ad84c5b6", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/InvoiceRequest" }, { "properties": { "attachments": { "$ref": "#/components/schemas/UserAttachments" } }, "type": "object" } ] } } } }, "responses": { "200": { "description": "Documento soporte creado" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/auto-increment/credit-notes": { "post": { "tags": [ "Documentos con Consecutivo Automático" ], "summary": "Crear Nota Crédito con consecutivo automático", "operationId": "5334e68fcd6a7e52250678e375f8a9ff", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/InvoiceRequest" }, { "properties": { "attachments": { "$ref": "#/components/schemas/UserAttachments" } }, "type": "object" } ] } } } }, "responses": { "200": { "description": "Nota crédito creada" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/auto-increment/debit-notes": { "post": { "tags": [ "Documentos con Consecutivo Automático" ], "summary": "Crear Nota Débito con consecutivo automático", "operationId": "6aba5b752ad055ca28b6db91d07cf0d9", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/InvoiceRequest" }, { "properties": { "attachments": { "$ref": "#/components/schemas/UserAttachments" } }, "type": "object" } ] } } } }, "responses": { "200": { "description": "Nota débito creada" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/auto-increment/pos-documents": { "post": { "tags": [ "Documentos con Consecutivo Automático" ], "summary": "Crear Documento POS con consecutivo automático", "operationId": "db4a5b8ca34a4d50a99af9b2be0ed1db", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/InvoiceRequest" }, { "properties": { "attachments": { "$ref": "#/components/schemas/UserAttachments" } }, "type": "object" } ] } } } }, "responses": { "200": { "description": "Documento POS creado" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/auto-increment/adjustment-notes": { "post": { "tags": [ "Documentos con Consecutivo Automático" ], "summary": "Crear una Nota de Ajuste con consecutivo automático", "operationId": "00e11a366ea473a0c330882958a2f6a5", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "description": "Datos de la nota de ajuste. El campo `document_number` debe ser omitido.", "required": true, "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/InvoiceRequest" }, { "properties": { "attachments": { "$ref": "#/components/schemas/UserAttachments" } }, "type": "object" } ] } } } }, "responses": { "200": { "description": "Documento procesado exitosamente" }, "402": { "description": "Límite de membresía alcanzado" }, "422": { "description": "Error de validación" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/invoice": { "post": { "tags": [ "Documentos Electrónicos" ], "summary": "Crear una Factura Electrónica con número de documento manual", "operationId": "2616b5e627406f3c60696e0a032b5099", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "description": "Datos de la factura a crear", "required": true, "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/InvoiceRequest" }, { "properties": { "attachments": { "$ref": "#/components/schemas/UserAttachments" } }, "type": "object" } ] } } } }, "responses": { "200": { "description": "Factura creada exitosamente. Si la DIAN ya había autorizado el mismo número (regla 90, o una clave autorizada tras un 98/timeout) se devuelve el documento autorizado (su XML, CUFE/CUDE y QR) con la advertencia ALREADY_AUTHORIZED_RECOVERED en `warnings`; si la DIAN lo autorizó con otro contenido, la respuesta es un rechazo con la advertencia ALREADY_AUTHORIZED_OTHER_CONTENT (o ALREADY_PROCESSED_NOT_CONFIRMED si la DIAN no confirma la clave)" }, "402": { "description": "Límite de membresía alcanzado" }, "409": { "description": "code DOCUMENT_IN_TRANSMISSION: el mismo documento (empresa, tipo y número) ya se está transmitiendo a la DIAN en otra solicitud. code DOCUMENT_IN_VALIDATION: la DIAN aún está validando (98) el envío anterior de ese número (data.document_key). En ambos casos no se transmitió; consulte su estado antes de reenviarlo" }, "422": { "description": "Error de validación" }, "503": { "description": "code DIAN_STATUS_UNAVAILABLE: el número ya tiene un envío anterior sin validar (data.document_key) y no se pudo confirmar su estado en la DIAN. No se transmitió de nuevo para no duplicarlo; intente en unos minutos" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/notes/credit": { "post": { "tags": [ "Documentos Electrónicos" ], "summary": "Crear una Nota Crédito o Débito", "operationId": "77a5f706949ff8a13417a5f1179e82c7", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "description": "Datos de la nota a crear", "required": true, "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/InvoiceRequest" }, { "properties": { "attachments": { "$ref": "#/components/schemas/UserAttachments" } }, "type": "object" } ] } } } }, "responses": { "200": { "description": "Nota creada exitosamente. Si la DIAN ya había autorizado el mismo número (regla 90, o una clave autorizada tras un 98/timeout) se devuelve el documento autorizado (su XML, CUFE/CUDE y QR) con la advertencia ALREADY_AUTHORIZED_RECOVERED en `warnings`; si la DIAN lo autorizó con otro contenido, la respuesta es un rechazo con la advertencia ALREADY_AUTHORIZED_OTHER_CONTENT (o ALREADY_PROCESSED_NOT_CONFIRMED si la DIAN no confirma la clave)" }, "402": { "description": "Límite de membresía alcanzado" }, "409": { "description": "code DOCUMENT_IN_TRANSMISSION: el mismo documento (empresa, tipo y número) ya se está transmitiendo a la DIAN en otra solicitud. code DOCUMENT_IN_VALIDATION: la DIAN aún está validando (98) el envío anterior de ese número (data.document_key). En ambos casos no se transmitió; consulte su estado antes de reenviarlo" }, "422": { "description": "Error de validación" }, "503": { "description": "code DIAN_STATUS_UNAVAILABLE: el número ya tiene un envío anterior sin validar (data.document_key) y no se pudo confirmar su estado en la DIAN. No se transmitió de nuevo para no duplicarlo; intente en unos minutos" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/ds/document": { "post": { "tags": [ "Documentos Electrónicos" ], "summary": "Crear un Documento Soporte", "operationId": "1fc67adf23d764e08715ca95621f7794", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "description": "Datos del documento soporte a crear", "required": true, "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/InvoiceRequest" }, { "properties": { "attachments": { "$ref": "#/components/schemas/UserAttachments" } }, "type": "object" } ] } } } }, "responses": { "200": { "description": "Documento soporte creado exitosamente. Si la DIAN ya había autorizado el mismo número (regla 90, o una clave autorizada tras un 98/timeout) se devuelve el documento autorizado (su XML, CUFE/CUDE y QR) con la advertencia ALREADY_AUTHORIZED_RECOVERED en `warnings`; si la DIAN lo autorizó con otro contenido, la respuesta es un rechazo con la advertencia ALREADY_AUTHORIZED_OTHER_CONTENT (o ALREADY_PROCESSED_NOT_CONFIRMED si la DIAN no confirma la clave)" }, "402": { "description": "Límite de membresía alcanzado" }, "409": { "description": "code DOCUMENT_IN_TRANSMISSION: el mismo documento (empresa, tipo y número) ya se está transmitiendo a la DIAN en otra solicitud. code DOCUMENT_IN_VALIDATION: la DIAN aún está validando (98) el envío anterior de ese número (data.document_key). En ambos casos no se transmitió; consulte su estado antes de reenviarlo" }, "422": { "description": "Error de validación" }, "503": { "description": "code DIAN_STATUS_UNAVAILABLE: el número ya tiene un envío anterior sin validar (data.document_key) y no se pudo confirmar su estado en la DIAN. No se transmitió de nuevo para no duplicarlo; intente en unos minutos" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/ds/adjustment-note": { "post": { "tags": [ "Documentos Electrónicos" ], "summary": "Crear una Nota de Ajuste para Documento Soporte", "operationId": "b610539f44e2bae9ef5f704a10a491c9", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "description": "Datos de la nota de ajuste", "required": true, "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/InvoiceRequest" }, { "properties": { "attachments": { "$ref": "#/components/schemas/UserAttachments" } }, "type": "object" } ] } } } }, "responses": { "200": { "description": "Nota de ajuste creada exitosamente. Si la DIAN ya había autorizado el mismo número (regla 90, o una clave autorizada tras un 98/timeout) se devuelve el documento autorizado (su XML, CUFE/CUDE y QR) con la advertencia ALREADY_AUTHORIZED_RECOVERED en `warnings`; si la DIAN lo autorizó con otro contenido, la respuesta es un rechazo con la advertencia ALREADY_AUTHORIZED_OTHER_CONTENT (o ALREADY_PROCESSED_NOT_CONFIRMED si la DIAN no confirma la clave)" }, "402": { "description": "Límite de membresía alcanzado" }, "409": { "description": "code DOCUMENT_IN_TRANSMISSION: el mismo documento (empresa, tipo y número) ya se está transmitiendo a la DIAN en otra solicitud. code DOCUMENT_IN_VALIDATION: la DIAN aún está validando (98) el envío anterior de ese número (data.document_key). En ambos casos no se transmitió; consulte su estado antes de reenviarlo" }, "422": { "description": "Error de validación" }, "503": { "description": "code DIAN_STATUS_UNAVAILABLE: el número ya tiene un envío anterior sin validar (data.document_key) y no se pudo confirmar su estado en la DIAN. No se transmitió de nuevo para no duplicarlo; intente en unos minutos" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/ep/payroll": { "post": { "tags": [ "Nómina Electrónica" ], "summary": "Crear una Nómina Electrónica", "operationId": "32e76e5e4fe03152c49a248b8fd91084", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "description": "Datos de la nómina a crear", "required": true, "content": { "application/json": { "schema": { "properties": { "companyId": { "description": "Opcional. UUID de la empresa cliente.", "type": "string", "format": "uuid", "example": "9d115e84-1cfa-42f8-a1dd-93339393e114" }, "attachments": { "$ref": "#/components/schemas/UserAttachments" } }, "type": "object" } } } }, "responses": { "200": { "description": "Nómina creada exitosamente" }, "402": { "description": "Límite de membresía alcanzado" }, "422": { "description": "Error de validación" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/ep/payroll/replace": { "post": { "tags": [ "Nómina Electrónica" ], "summary": "Reemplazar una Nómina Electrónica", "operationId": "6be051ee92c1e721ef990e6dd047a0ed", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "description": "Datos de la nómina de reemplazo", "required": true, "content": { "application/json": { "schema": { "properties": { "companyId": { "description": "Opcional. UUID de la empresa cliente.", "type": "string", "format": "uuid", "example": "9d115e84-1cfa-42f8-a1dd-93339393e114" }, "attachments": { "$ref": "#/components/schemas/UserAttachments" } }, "type": "object" } } } }, "responses": { "200": { "description": "Nómina de reemplazo creada exitosamente" }, "402": { "description": "Límite de membresía alcanzado" }, "422": { "description": "Error de validación" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/ep/payroll/delete": { "post": { "tags": [ "Nómina Electrónica" ], "summary": "Eliminar una Nómina Electrónica", "operationId": "2d6b5b6d3a55825d9a27d2010cd0e649", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "description": "Datos de la nómina a eliminar", "required": true, "content": { "application/json": { "schema": { "properties": { "companyId": { "description": "Opcional. UUID de la empresa cliente.", "type": "string", "format": "uuid", "example": "9d115e84-1cfa-42f8-a1dd-93339393e114" } }, "type": "object" } } } }, "responses": { "200": { "description": "Nómina eliminada exitosamente" }, "402": { "description": "Límite de membresía alcanzado" }, "422": { "description": "Error de validación" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/numbers-to-letters": { "get": { "tags": [ "Funciones Auxiliares" ], "summary": "Convertir números a letras", "operationId": "4cff98e9fb31f55d2081ee07671b3378", "parameters": [ { "name": "number", "in": "query", "description": "Número a convertir", "required": true, "schema": { "type": "number", "format": "float" } }, { "name": "money", "in": "query", "description": "Nombre de la moneda principal", "required": false, "schema": { "type": "string", "default": "PESOS" } }, { "name": "money2", "in": "query", "description": "Nombre de la moneda secundaria (centavos)", "required": false, "schema": { "type": "string", "default": "CENTAVOS" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Número convertido a letras exitosamente", "content": { "application/json": { "schema": { "type": "string" }, "example": "CIEN MIL PESOS CON CINCUENTA CENTAVOS" } } } } } }, "/api/digit-verification": { "get": { "tags": [ "Funciones Auxiliares" ], "summary": "Calcular dígito de verificación", "operationId": "b53f5aa2c9485a39f39c474b40480a3b", "parameters": [ { "name": "Number", "in": "query", "description": "Número de identificación (NIT)", "required": true, "schema": { "type": "integer" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Dígito de verificación calculado exitosamente", "content": { "application/json": { "schema": { "properties": { "digit": { "type": "integer", "example": 7 }, "nit": { "type": "string", "example": "900123456-7" } }, "type": "object" } } } } } } }, "/api/ubl2.1/tokens": { "get": { "tags": [ "Personal Access Tokens" ], "summary": "Listar tokens del usuario", "description": "Obtiene todos los Personal Access Tokens del usuario autenticado, incluyendo tokens activos y revocados.", "operationId": "listTokens", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Lista de tokens obtenida exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "dataRecords": { "properties": { "data": { "type": "array", "items": { "properties": { "id": { "type": "string", "example": "9c7a1b2e-3f4d-5e6a-7b8c-9d0e1f2a3b4c" }, "name": { "type": "string", "example": "Production API Token" }, "scopes": { "type": "array", "items": { "type": "string" } }, "revoked": { "type": "boolean", "example": false }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "total": { "type": "integer", "example": 5 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "No autenticado", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Personal Access Tokens" ], "summary": "Crear nuevo token", "description": "Crea un nuevo Personal Access Token para el usuario autenticado. Límite: 10 tokens por día.", "operationId": "createToken", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "description": "Nombre descriptivo del token", "type": "string", "example": "Production API Token" }, "description": { "description": "Descripción opcional del uso del token", "type": "string", "example": "Token para integraciones de producción" }, "expires_in_days": { "description": "Días hasta expiración (1-365, default: 90)", "type": "integer", "example": 90 } }, "type": "object" } } } }, "responses": { "201": { "description": "Token creado exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Personal access token created successfully" }, "dataRecords": { "properties": { "data": { "properties": { "accessToken": { "type": "string", "example": "eyJ0eXAiOiJKV1QiLCJhbGciOi..." }, "token_id": { "type": "string", "example": "9c7a1b2e-3f4d-5e6a-7b8c-9d0e1f2a3b4c" }, "name": { "type": "string", "example": "Production API Token" }, "expires_at": { "type": "string", "format": "date-time", "example": "2026-04-15T10:30:00.000000Z" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Errores de validación", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The name field is required." }, "errors": { "properties": { "name": { "type": "array", "items": { "type": "string", "example": "The name field is required." } } }, "type": "object" } }, "type": "object" } } } }, "429": { "description": "Rate limit excedido", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too many tokens created. You can create up to 10 tokens per day." }, "error": { "type": "string", "example": "Rate limit exceeded" }, "retry_after": { "type": "integer", "example": 3600 } }, "type": "object" } } } }, "500": { "description": "Error al crear token", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Error al crear el token" }, "error": { "type": "string" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/tokens/{id}": { "get": { "tags": [ "Personal Access Tokens" ], "summary": "Ver detalle de token", "description": "Obtiene los detalles completos de un Personal Access Token específico del usuario autenticado.", "operationId": "showToken", "parameters": [ { "name": "id", "in": "path", "description": "ID del token", "required": true, "schema": { "type": "string", "example": "9c7a1b2e-3f4d-5e6a-7b8c-9d0e1f2a3b4c" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Detalles del token obtenidos exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "dataRecords": { "properties": { "data": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "revoked": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "No autorizado - Token no pertenece al usuario", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "404": { "description": "Token no encontrado", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Token not found" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Personal Access Tokens" ], "summary": "Revocar token específico", "description": "Revoca un Personal Access Token específico del usuario autenticado.", "operationId": "revokeToken", "parameters": [ { "name": "id", "in": "path", "description": "ID del token a revocar", "required": true, "schema": { "type": "string", "example": "9c7a1b2e-3f4d-5e6a-7b8c-9d0e1f2a3b4c" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "reason": { "description": "Razón de la revocación (opcional)", "type": "string", "example": "Compromised token" } }, "type": "object" } } } }, "responses": { "200": { "description": "Token revocado exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Token revoked successfully" } }, "type": "object" } } } }, "400": { "description": "Error al revocar token", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Failed to revoke token" }, "error": { "type": "string" } }, "type": "object" } } } }, "404": { "description": "Token no encontrado" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/tokens/revoke-all": { "post": { "tags": [ "Personal Access Tokens" ], "summary": "Revocar todos los tokens", "description": "Revoca todos los Personal Access Tokens del usuario autenticado excepto el token actual en uso.", "operationId": "revokeAllTokens", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Tokens revocados exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Tokens revoked successfully" }, "dataRecords": { "properties": { "data": { "properties": { "revoked_count": { "type": "integer", "example": 3 } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Error al revocar tokens", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Failed to revoke tokens" }, "error": { "type": "string" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/exchange-emails": { "get": { "tags": [ "Consultas" ], "summary": "Obtener correos electrónicos de intercambio de documentos", "operationId": "70a377998045d224a28fd6170288bad0", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Consulta generada con éxito", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Consulta generada con éxito" }, "exchangeEmailData": { "description": "Datos de correos en formato Base64", "type": "string" } }, "type": "object" } } } }, "401": { "description": "No autenticado" }, "403": { "description": "error_code NOT_AVAILABLE_IN_SANDBOX: no disponible en sandbox (requiere el certificado real). how_to_proceed indica cómo enviar el correo del adquiriente al emitir" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/numbering-range": { "get": { "tags": [ "Consultas" ], "summary": "Obtener el rango de numeración de resoluciones DIAN", "operationId": "e6afb29e410afc4212c56d1c6d0a772f", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Rango de numeración obtenido exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "No autenticado" }, "403": { "description": "error_code NOT_AVAILABLE_IN_SANDBOX: no disponible en sandbox (requiere el certificado real). how_to_proceed indica cómo registrar la resolución con POST /api/ubl2.1/resolutions" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/status/zip/{trackId}": { "post": { "tags": [ "Estado de Documentos" ], "summary": "Obtener el estado de un documento ZIP", "operationId": "8bac4158a245e4ff46124427faadf11d", "parameters": [ { "name": "trackId", "in": "path", "description": "ID de rastreo del documento", "required": true, "schema": { "type": "string" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Estado obtenido exitosamente" }, "403": { "description": "error_code NOT_AVAILABLE_IN_SANDBOX: el sandbox no hace envíos asíncronos; el resultado llega en response del envío. how_to_proceed indica cómo consultarlo" }, "404": { "description": "Documento no encontrado" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/status/document/test/{trackId}": { "post": { "tags": [ "Estado de Documentos" ], "summary": "Obtener el estado de un documento de prueba", "operationId": "4923efcd8de149d0098d50a894c077cd", "parameters": [ { "name": "trackId", "in": "path", "description": "ID de rastreo del documento", "required": true, "schema": { "type": "string" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Estado obtenido exitosamente" }, "403": { "description": "error_code NOT_AVAILABLE_IN_SANDBOX: el sandbox no llega al ambiente de habilitación de la DIAN; el resultado llega en response del envío. how_to_proceed indica cómo consultarlo" }, "404": { "description": "Documento no encontrado" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/status/document/{trackId}": { "post": { "tags": [ "Estado de Documentos" ], "summary": "Obtener el estado de un documento electrónico", "operationId": "d9a504546d09400ce31b9a7e06ab6da5", "parameters": [ { "name": "trackId", "in": "path", "description": "ID de rastreo del documento", "required": true, "schema": { "type": "string" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Estado obtenido exitosamente" }, "404": { "description": "Documento no encontrado" }, "409": { "description": "code DOCUMENT_IN_TRANSMISSION: el número se está transmitiendo a la DIAN en otra solicitud; consulte de nuevo en unos minutos" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/status": { "get": { "tags": [ "Estado de Documentos" ], "summary": "Consultar el estado de un documento por número", "description": "Si hay varias filas para el número (parámetro number) se prefiere la validada por la DIAN y luego la más reciente; sin number, la más reciente. is_valid es true solo cuando la DIAN validó el documento; validation_state detalla el estado. qr.data (texto del QR en base64) y qr.qrDian corresponden a document_key.", "operationId": "6b14be75cf76754646dbc6acaa560d31", "parameters": [ { "name": "number", "in": "query", "description": "Número del documento con prefijo (ej. NC3)", "required": false, "schema": { "type": "string" } }, { "name": "prefix", "in": "query", "description": "Prefijo de la resolución", "required": false, "schema": { "type": "string" } }, { "name": "resolution", "in": "query", "description": "Número de resolución", "required": false, "schema": { "type": "string" } }, { "name": "order_number", "in": "query", "description": "Número de orden del cliente", "required": false, "schema": { "type": "string" } }, { "name": "type_document_id", "in": "query", "description": "Id del tipo de documento (también se acepta document_type). Un valor no numérico se ignora", "required": false, "schema": { "type": "integer" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Estado obtenido exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" }, "document": { "properties": { "uuid": { "type": "string" }, "document_number": { "type": "string" }, "order_number": { "type": "string", "nullable": true }, "document_key": { "description": "CUFE/CUDE vigente (XmlDocumentKey)", "type": "string" }, "document_name": { "type": "string" }, "is_valid": { "description": "true solo si la DIAN validó el documento", "type": "boolean" }, "validation_state": { "type": "string", "enum": [ "VALID", "NOT_VALIDATED", "PENDING_REVALIDATION", "NOT_FOUND_OR_REJECTED", "CERTIFICATE_EXPIRED", "PENDING_RESEND", "PENDING", "UNKNOWN" ] }, "type_document_id": { "type": "integer" }, "invoice_date": { "type": "string" }, "qr": { "properties": { "qrDian": { "description": "URL de consulta de la DIAN con document_key", "type": "string", "nullable": true }, "data": { "description": "Texto del QR en base64, con document_key", "type": "string", "nullable": true }, "path": { "description": "Siempre null (se conserva por compatibilidad)", "type": "string", "nullable": true }, "url": { "description": "Siempre null (se conserva por compatibilidad)", "type": "string", "nullable": true } }, "type": "object" } }, "type": "object" }, "status": { "type": "string" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "No autenticado" }, "404": { "description": "Documento no encontrado" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "Listar webhooks de la empresa", "description": "Obtiene todos los webhooks configurados para la empresa del usuario autenticado, incluyendo estadísticas de entregas y entregas recientes.", "operationId": "listWebhooks", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Lista de webhooks obtenida exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "dataRecords": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "total": { "type": "integer", "example": 5 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "No autenticado" }, "403": { "description": "Usuario no tiene empresa asociada", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Usuario no tiene empresa asociada" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Webhooks" ], "summary": "Crear webhook", "description": "Crea un nuevo webhook para la empresa. Genera automáticamente un secret HMAC-SHA256 para verificación de firmas.", "operationId": "createWebhook", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "url", "events" ], "properties": { "name": { "description": "Nombre descriptivo del webhook", "type": "string", "example": "Webhook Principal" }, "url": { "description": "URL HTTPS del endpoint que recibirá los webhooks", "type": "string", "format": "uri", "example": "https://n8n.cliente.com/webhook/apidian" }, "events": { "description": "Array de eventos a los que suscribirse", "type": "array", "items": { "type": "string" }, "example": [ "document.created", "document.emitted", "email.sent" ] }, "headers": { "description": "Headers personalizados para incluir en cada webhook (ej: Authorization)", "type": "object", "example": { "Authorization": "Bearer mi-token-secreto" }, "nullable": true }, "is_active": { "description": "Si el webhook está activo (default: true)", "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Webhook creado exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Webhook creado exitosamente" }, "dataRecords": { "properties": { "data": { "$ref": "#/components/schemas/Webhook" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "No autenticado" }, "403": { "description": "Usuario no tiene empresa asociada" }, "422": { "description": "Datos de entrada inválidos", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "URL debe ser HTTPS en producción" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/webhooks/events": { "get": { "tags": [ "Webhooks" ], "summary": "Listar eventos disponibles", "description": "Obtiene todos los eventos de webhook disponibles organizados por categoría (documentos, emails, pagos, membresías).", "operationId": "listWebhookEvents", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Lista de eventos obtenida exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "dataRecords": { "properties": { "data": { "properties": { "documents": { "type": "array", "items": { "properties": { "value": { "type": "string", "example": "document.created" }, "label": { "type": "string", "example": "Documento Creado" } }, "type": "object" } }, "emails": { "type": "array", "items": { "properties": { "value": { "type": "string", "example": "email.sent" }, "label": { "type": "string", "example": "Email Enviado" } }, "type": "object" } }, "payments": { "type": "array", "items": { "properties": { "value": { "type": "string", "example": "payment.approved" }, "label": { "type": "string", "example": "Pago Aprobado" } }, "type": "object" } }, "memberships": { "type": "array", "items": { "properties": { "value": { "type": "string", "example": "membership.activated" }, "label": { "type": "string", "example": "Membresía Activada" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "No autenticado" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/webhooks/{id}": { "get": { "tags": [ "Webhooks" ], "summary": "Obtener detalles de webhook", "description": "Obtiene la información completa de un webhook específico incluyendo su secret y estadísticas.", "operationId": "getWebhook", "parameters": [ { "name": "id", "in": "path", "description": "ID del webhook", "required": true, "schema": { "type": "integer", "example": 1 } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Detalles del webhook", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "dataRecords": { "properties": { "data": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "url": { "type": "string" }, "secret": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "headers": { "type": "object", "nullable": true }, "is_active": { "type": "boolean" }, "last_triggered_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "stats": { "$ref": "#/components/schemas/WebhookStats" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "No autenticado" }, "403": { "description": "Usuario no tiene empresa asociada" }, "404": { "description": "Webhook no encontrado" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Webhooks" ], "summary": "Actualizar webhook", "description": "Actualiza la configuración de un webhook existente (nombre, URL, eventos, headers, estado activo).", "operationId": "updateWebhook", "parameters": [ { "name": "id", "in": "path", "description": "ID del webhook", "required": true, "schema": { "type": "integer", "example": 1 } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "example": "Webhook Actualizado" }, "url": { "type": "string", "format": "uri", "example": "https://nuevo-endpoint.com/webhook" }, "events": { "type": "array", "items": { "type": "string" }, "example": [ "document.created", "email.sent" ] }, "headers": { "type": "object", "nullable": true }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Webhook actualizado exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Webhook actualizado exitosamente" }, "dataRecords": { "properties": { "data": { "$ref": "#/components/schemas/Webhook" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "No autenticado" }, "403": { "description": "Usuario no tiene empresa asociada" }, "404": { "description": "Webhook no encontrado" }, "422": { "description": "Datos inválidos" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Webhooks" ], "summary": "Eliminar webhook", "description": "Elimina un webhook de forma permanente. También elimina todo su historial de entregas.", "operationId": "deleteWebhook", "parameters": [ { "name": "id", "in": "path", "description": "ID del webhook", "required": true, "schema": { "type": "integer", "example": 1 } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Webhook eliminado exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Webhook eliminado exitosamente" } }, "type": "object" } } } }, "401": { "description": "No autenticado" }, "403": { "description": "Usuario no tiene empresa asociada" }, "404": { "description": "Webhook no encontrado" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/webhooks/{id}/test": { "post": { "tags": [ "Webhooks" ], "summary": "Probar webhook", "description": "Envía un webhook de prueba al endpoint configurado con un payload de ejemplo. Útil para verificar la configuración sin esperar eventos reales.", "operationId": "testWebhook", "parameters": [ { "name": "id", "in": "path", "description": "ID del webhook", "required": true, "schema": { "type": "integer", "example": 1 } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Webhook enviado exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Webhook enviado exitosamente" }, "dataRecords": { "properties": { "data": { "properties": { "delivery_id": { "type": "integer", "example": 42 }, "status_code": { "type": "integer", "example": 200 }, "response": { "type": "string", "example": "Response body" }, "delivered_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "No autenticado" }, "403": { "description": "Usuario no tiene empresa asociada" }, "404": { "description": "Webhook no encontrado" }, "424": { "description": "Fallo al enviar webhook", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Error al enviar webhook" }, "dataRecords": { "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/webhooks/{id}/deliveries/{deliveryId}/retry": { "post": { "tags": [ "Webhooks" ], "summary": "Reintentar una entrega puntual", "description": "Fuerza el reintento inmediato de una entrega de webhook específica (ya sea 'pending' o 'failed'), sin esperar el backoff programado y sin volver a emitir el documento asociado. Si la entrega ya agotó los 6 intentos, reinicia el contador para permitir un intento manual explícito.", "operationId": "retryWebhookDelivery", "parameters": [ { "name": "id", "in": "path", "description": "ID del webhook", "required": true, "schema": { "type": "integer", "example": 1 } }, { "name": "deliveryId", "in": "path", "description": "ID de la entrega a reintentar", "required": true, "schema": { "type": "integer", "example": 42 } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Entrega reintentada y confirmada exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Entrega reintentada y confirmada exitosamente" }, "dataRecords": { "properties": { "data": { "properties": { "delivery_id": { "type": "integer", "example": 42 }, "status_code": { "type": "integer", "example": 200 }, "response": { "type": "string", "example": "Response body" }, "retry_count": { "type": "integer", "example": 2 }, "delivered_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "No autenticado" }, "403": { "description": "Usuario no tiene empresa asociada" }, "404": { "description": "Webhook o entrega no encontrados" }, "424": { "description": "El reintento falló nuevamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "El reintento falló nuevamente. Revise la respuesta del endpoint receptor." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/webhooks/{id}/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "Historial de entregas del webhook", "description": "Obtiene el historial paginado de todas las entregas (exitosas y fallidas) de un webhook específico.", "operationId": "getWebhookDeliveries", "parameters": [ { "name": "id", "in": "path", "description": "ID del webhook", "required": true, "schema": { "type": "integer", "example": 1 } }, { "name": "page", "in": "query", "description": "Número de página a consultar", "schema": { "type": "integer", "default": 1 } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "dataRecords": { "properties": { "current_page": { "type": "integer", "example": 1 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "first_page_url": { "type": "string", "example": "https://api.apidian.co/api/ubl2.1/webhooks/1/deliveries?page=1", "nullable": true }, "from": { "type": "integer", "example": 1, "nullable": true }, "last_page": { "type": "integer", "example": 3 }, "last_page_url": { "type": "string", "example": "https://api.apidian.co/api/ubl2.1/webhooks/1/deliveries?page=3", "nullable": true }, "links": { "type": "array", "items": { "properties": { "url": { "type": "string", "nullable": true }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "type": "object" } }, "next_page_url": { "type": "string", "example": "https://api.apidian.co/api/ubl2.1/webhooks/1/deliveries?page=2", "nullable": true }, "path": { "type": "string", "example": "https://api.apidian.co/api/ubl2.1/webhooks/1/deliveries" }, "per_page": { "type": "integer", "example": 15 }, "prev_page_url": { "type": "string", "example": null, "nullable": true }, "to": { "type": "integer", "example": 15, "nullable": true }, "total": { "type": "integer", "example": 42 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "No autenticado" }, "403": { "description": "Usuario no tiene empresa asociada" }, "404": { "description": "Webhook no encontrado" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/webhooks/{id}/regenerate-secret": { "post": { "tags": [ "Webhooks" ], "summary": "Regenerar secret del webhook", "description": "Genera un nuevo secret HMAC-SHA256 para el webhook. Útil en casos de rotación de secrets o compromiso de seguridad. El nuevo secret se aplica inmediatamente a todos los webhooks futuros.", "operationId": "regenerateWebhookSecret", "parameters": [ { "name": "id", "in": "path", "description": "ID del webhook", "required": true, "schema": { "type": "integer", "example": 1 } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Secret regenerado exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Secret regenerado exitosamente" }, "dataRecords": { "properties": { "data": { "type": "string", "example": "whsec_nZ7yX5wV3uT1sR9qP8oN6mL4kJ2iH0gF" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "No autenticado" }, "403": { "description": "Usuario no tiene empresa asociada" }, "404": { "description": "Webhook no encontrado" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/profile/types": { "get": { "tags": [ "Autenticación" ], "summary": "Obtener tipos de usuario", "operationId": "a3f6b874bbb30487227be33b67ec9ba5", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Tipos de usuario obtenidos exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/auth/login": { "post": { "tags": [ "Autenticación" ], "summary": "Iniciar sesión", "operationId": "c763a494ef71eff4ac379e6d5026076f", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "example": "usuario@example.com" }, "password": { "type": "string", "format": "password", "example": "password123" }, "remember_me": { "description": "Opcional. Mantener la sesión iniciada", "type": "boolean", "example": false } }, "type": "object" } } } }, "responses": { "200": { "description": "Login exitoso", "content": { "application/json": { "schema": { "properties": { "access_token": { "type": "string" }, "token_id": { "type": "integer", "example": 12345 }, "user": { "type": "object" }, "expires_at": { "type": "string", "format": "date-time", "example": "2026-09-01 10:30:00" }, "message": { "type": "string", "example": "Bienvenido. Su sesión ha sido iniciada con éxito." } }, "type": "object" } } } }, "404": { "description": "Credenciales inválidas, usuario/empresa inactivos o correo no verificado", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Credenciales inválidas." } }, "type": "object" } } } }, "422": { "description": "Error de validación en campos requeridos" }, "500": { "description": "Error interno al generar token o registrar auditoría" } } } }, "/api/ubl2.1/auth/logout": { "get": { "tags": [ "Autenticación" ], "summary": "Cerrar sesión", "operationId": "b92039d849f9406660fda77533357ec9", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Sesión cerrada exitosamente", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Successfully logged out" } }, "type": "object" } } } }, "500": { "description": "Error interno al cerrar sesión" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/auth/user": { "get": { "tags": [ "Autenticación" ], "summary": "Obtener usuario autenticado", "operationId": "e0edc89b7ede9a3e7d55085a08f0fda8", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Usuario obtenido exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "dataRecords": { "properties": { "data": { "type": "array", "items": { "description": "Usuario autenticado", "type": "object" } } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/profile/{id}": { "put": { "tags": [ "Perfil" ], "summary": "Actualizar perfil de usuario", "operationId": "bce99956c2b1a17d1285adeac714dc0c", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "imgdata": { "description": "Imagen en base64", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Perfil actualizado exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "dataRecords": { "properties": { "data": { "description": "Datos de usuario actualizados", "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Error de validación o usuario no autorizado" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/profile/{id}/image": { "put": { "tags": [ "Perfil" ], "summary": "Actualizar imagen de perfil del usuario", "operationId": "5be8cbca8406f51eff47306c9e726f74", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "imgdata": { "description": "Imagen en base64", "type": "string" }, "imgname": { "description": "Nombre del archivo de imagen", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Imagen de perfil actualizada exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "dataRecords": { "properties": { "data": { "description": "Datos de usuario actualizados con nueva imagen", "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Error al actualizar la imagen de perfil" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/profile/update-email": { "put": { "tags": [ "Perfil" ], "summary": "Actualizar correo electrónico del usuario", "description": "Permite al usuario actualizar su correo electrónico. Requiere que el nuevo correo no esté en uso por otro usuario. El email_verified_at se establece en null y se envía automáticamente un correo de verificación al nuevo email.", "operationId": "updateUserEmail", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "description": "Datos necesarios para actualizar el correo electrónico", "required": true, "content": { "application/json": { "schema": { "required": [ "email" ], "properties": { "email": { "description": "Nuevo correo electrónico del usuario", "type": "string", "format": "email", "example": "nuevo@ejemplo.com" } }, "type": "object" } } } }, "responses": { "200": { "description": "Correo electrónico actualizado exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Correo electrónico actualizado exitosamente. Se ha enviado un correo de verificación a tu nuevo email." }, "dataRecords": { "properties": { "data": { "properties": { "email": { "description": "Nuevo correo electrónico", "type": "string", "format": "email", "example": "nuevo@ejemplo.com" }, "email_verified_at": { "description": "Fecha de verificación del email (null porque se requiere nueva verificación)", "type": "string", "example": null, "nullable": true }, "previous_email": { "description": "Correo electrónico anterior", "type": "string", "format": "email", "example": "anterior@ejemplo.com" }, "verification_sent": { "description": "Indica si se envió el correo de verificación", "type": "boolean", "example": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "No autenticado - Token inválido o no proporcionado", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "422": { "description": "Validación fallida - Email duplicado, inválido o datos incorrectos", "content": { "application/json": { "schema": { "oneOf": [ { "properties": { "message": { "type": "string", "example": "El correo electrónico ya está en uso" }, "errors": { "properties": { "email": { "type": "array", "items": { "type": "string", "example": "El correo electrónico ya está en uso" } } }, "type": "object" } }, "type": "object" }, { "properties": { "message": { "type": "string", "example": "El correo electrónico debe ser una dirección válida" }, "errors": { "properties": { "email": { "type": "array", "items": { "type": "string", "example": "El correo electrónico debe ser una dirección válida" } } }, "type": "object" } }, "type": "object" }, { "properties": { "message": { "type": "string", "example": "El correo electrónico es obligatorio" }, "errors": { "properties": { "email": { "type": "array", "items": { "type": "string", "example": "El correo electrónico es obligatorio" } } }, "type": "object" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/forgot-password": { "post": { "tags": [ "Recuperación de Contraseña" ], "summary": "Solicitar link de restablecimiento de contraseña", "operationId": "16b8fc9eb215030aec4532429897e081", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "example": "usuario@example.com" } }, "type": "object" } } } }, "responses": { "200": { "description": "Link de restablecimiento enviado", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" } }, "type": "object" } } } }, "422": { "description": "Email no encontrado" } } } }, "/api/ubl2.1/register": { "post": { "tags": [ "Registro" ], "summary": "Registrar nueva empresa y usuario", "description": "Auto-registro público (sin token) de una cuenta principal: crea, en una sola transacción, un usuario DESARROLLADOR y su empresa. No crea sub-cuentas: para eso se usa `POST /api/ubl2.1/company/{uuid}/customer` con el token del desarrollador, y enviar `company_id` aquí responde 422. El usuario se crea siempre como DESARROLLADOR: `type_id` se ignora, con cualquier valor. Nombres y razón social se guardan en mayúsculas y el `dv` se calcula a partir del `dni`. Suscripción inicial de 1 año: plan FREE con 100 documentos en producción; en sandbox, plan 15 con 5000 documentos. No devuelve token ni datos del usuario o la empresa. El correo queda **sin verificar** y se envía el correo de verificación: hasta abrir su enlace, `POST /api/ubl2.1/auth/login` responde 404 (`El correo electrónico no ha sido verificado. Comuníquese con el administrador.`). Para reenviarlo: `POST /api/ubl2.1/email/verification-notification` con `email`. Si el envío del correo falla, responde 500 aunque el usuario y la empresa ya quedaron creados.", "operationId": "registerDeveloper", "parameters": [ { "name": "client_uuid", "in": "query", "description": "No aplica a este endpoint: se ignora.", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "first_name", "last_name", "company_name", "email", "password", "password_confirmation", "dni" ], "properties": { "first_name": { "type": "string", "maxLength": 100, "example": "Juan" }, "last_name": { "type": "string", "maxLength": 100, "example": "Pérez" }, "company_name": { "type": "string", "maxLength": 100, "example": "Mi Empresa SAS" }, "email": { "description": "Único en `users`. Se valida el formato RFC y que el dominio tenga DNS", "type": "string", "format": "email", "maxLength": 255, "example": "juan@miempresa.com" }, "password": { "type": "string", "format": "password", "minLength": 8 }, "password_confirmation": { "description": "Debe coincidir con `password`", "type": "string", "format": "password" }, "dni": { "description": "NIT o documento, solo dígitos (sin `dv`, puntos, guiones ni letras) y máximo 15. Único en `companies`. Con cualquier otro carácter responde 422 (`El NIT debe contener solo dígitos, sin puntos, guiones ni dígito de verificación`); con más de 15 dígitos, 422 (`El NIT no puede tener más de 15 dígitos`)", "type": "string", "maxLength": 15, "pattern": "^[0-9]+$", "example": "900123456" }, "country_id": { "description": "No se valida; un id inexistente responde 400 con el mensaje de la base de datos", "type": "integer", "default": 45 }, "city_id": { "description": "No se valida; un id inexistente responde 400 con el mensaje de la base de datos", "type": "integer", "default": 149 }, "identity_document_id": { "type": "integer", "default": 3 }, "type_organization_id": { "type": "integer", "default": 1 }, "tax_regime_id": { "type": "integer", "default": 1 }, "tax_level_id": { "type": "integer", "default": 5 }, "address": { "type": "string", "example": "Calle 123" }, "location": { "type": "string" }, "postal_code": { "type": "string" }, "mobile": { "type": "string", "example": "3001234567" }, "phone": { "type": "string", "example": "6012345678" }, "web": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Cuenta creada con el correo sin verificar. Se responde 200, no 201, y sin token", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Empresa creada con éxito. Verifique su dirección de correo electrónico: juan@miempresa.com" }, "success": { "type": "boolean", "example": true } }, "type": "object" } } } }, "400": { "description": "Un valor viola una restricción de integridad de la base de datos (por ejemplo, `country_id` o `city_id` inexistente). El `message` es el de la base de datos. No se crea nada (rollback)", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string" } }, "type": "object" } } } }, "422": { "description": "Errores de validación. Mensajes propios: `El nombre es requerido`, `El apellido es requerido`, `El nombre de la empresa es requerido`, `El correo electrónico es requerido`, `El correo electrónico no es válido o su dominio no existe`, `El correo electrónico ya existe`, `El NIT es requerido`, `El NIT ya existe`, `El NIT debe contener solo dígitos, sin puntos, guiones ni dígito de verificación`, `El NIT no puede tener más de 15 dígitos` y, si se envía `company_id`, `Este endpoint no crea sub-cuentas. Use POST /api/ubl2.1/company/{uuid}/customer con el token del desarrollador.` (las reglas de `password`, `max` y `string` usan los mensajes del framework)", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Este endpoint no crea sub-cuentas. Use POST /api/ubl2.1/company/{uuid}/customer con el token del desarrollador." }, "errors": { "type": "object", "example": { "company_id": [ "Este endpoint no crea sub-cuentas. Use POST /api/ubl2.1/company/{uuid}/customer con el token del desarrollador." ] } } }, "type": "object" } } } }, "429": { "description": "Límite de peticiones por minuto superado (throttle:api)" }, "500": { "description": "Cualquier otro error en la creación (no se crea nada), o fallo al enviar el correo de verificación (en este caso la cuenta sí quedó creada, sin verificar)", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Error interno del servidor. ..." }, "reference": { "type": "string", "format": "uuid" } }, "type": "object" } } } } } } }, "/api/ubl2.1/certificate": { "get": { "tags": [ "Certificados Digitales" ], "summary": "Obtener información del certificado", "operationId": "70e158220b8ac419eda6b3f67485178f", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Información del certificado obtenida exitosamente" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Certificados Digitales" ], "summary": "Crear/subir certificado digital", "operationId": "5636af13f9a935b3bf6bda31235c5eb9", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "properties": { "certificate": { "description": "Archivo .p12 o .pfx", "type": "string", "format": "binary" }, "password": { "description": "Contraseña del certificado", "type": "string" } }, "type": "object" } } } }, "responses": { "201": { "description": "Certificado creado exitosamente" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/certificate/expiration/{dni}": { "get": { "tags": [ "Certificados Digitales" ], "summary": "Obtener fecha de expiración del certificado", "operationId": "225dcc21b251a47ae5fdf90e126cee37", "parameters": [ { "name": "dni", "in": "path", "description": "Número de identificación de la empresa", "required": true, "schema": { "type": "string" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Fecha de expiración obtenida exitosamente", "content": { "application/json": { "schema": { "properties": { "expires_at": { "type": "string", "format": "date-time" }, "days_remaining": { "type": "integer" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/certificate/{id}": { "put": { "tags": [ "Certificados Digitales" ], "summary": "Actualizar certificado", "operationId": "0b985aad56f1860386ea719ad87e7e89", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Certificado actualizado exitosamente" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Certificados Digitales" ], "summary": "Eliminar certificado", "operationId": "9beef453c459fe51737250e05e0f60d8", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Certificado eliminado exitosamente" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/company/settings": { "get": { "tags": [ "Empresa" ], "summary": "Obtener configuración de la empresa", "operationId": "0a2afd1b07cf76c7c697fcd107b60846", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Configuración obtenida exitosamente", "content": { "application/json": { "schema": { "properties": { "settings": { "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Empresa" ], "summary": "Actualizar configuración de la empresa", "operationId": "ffef251d8b2614ac3b304acc75750caf", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "setting_key": { "type": "string", "example": "invoice_prefix" }, "setting_value": { "type": "string", "example": "FV" } }, "type": "object" } } } }, "responses": { "200": { "description": "Configuración actualizada exitosamente" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/company/customers/{uuid}": { "put": { "tags": [ "Clientes" ], "summary": "Actualizar los datos de un cliente", "description": "Actualiza la empresa de un cliente vinculado a la empresa del token. El cuerpo lleva un único campo `records`: un **string JSON** (no un objeto) con los atributos a cambiar. Solo se aplican los atributos editables de la empresa: `country_id`, `city_id`, `identity_document_id`, `type_organization_id`, `tax_regime_id`, `tax_level_id`, `company_name`, `trade_name`, `address`, `city_name`, `location`, `postal_code`, `mobile`, `phone`, `email`, `web`, `merchant_registration`, `image`, `extra_data`. Solo se guardan los valores que cambian y el cambio queda auditado. `dni` no se actualiza. Si `country_id` es el entero 45 (Colombia), el `dv` se recalcula a partir de `records.dni`, que en ese caso es obligatorio. `country_id` debe venir siempre dentro de `records`; si falta, responde 500. Opcional: `imgdata` (data URI en base64) + `imgname` (solo se usa su extensión: png, jpg, jpeg, gif, webp, svg, jfif, bmp o ico; cualquier otra se guarda como png) para cambiar el logo en la misma petición.", "operationId": "updateCustomer", "parameters": [ { "name": "uuid", "in": "path", "description": "UUID del cliente (sub-cuenta). No se acepta el id numérico.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "client_uuid", "in": "query", "description": "Se ignora: el cliente sobre el que se opera es siempre el del `{uuid}` de la ruta.", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "records" ], "properties": { "records": { "description": "String JSON con los atributos a actualizar (ver descripción)", "type": "string", "format": "json", "example": "{\"country_id\":45,\"dni\":\"900123456\",\"company_name\":\"CLIENTE SAS\",\"address\":\"Calle 123\",\"phone\":\"6012345678\"}" } }, "type": "object" } } } }, "responses": { "200": { "description": "Cliente actualizado. `dataRecords` es la empresa sin `id`, con `full_path_image` y sin relaciones", "content": { "application/json": { "schema": { "properties": { "dataRecords": { "type": "object" }, "message": { "type": "string", "example": "Registro actualizado correctamente." }, "success": { "type": "boolean", "example": true } }, "type": "object" } } } }, "400": { "description": "Violación de integridad en la base de datos (por ejemplo, un `country_id` o `city_id` que no existe). El mensaje es el del motor de BD", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Token ausente, inválido o expirado", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "El cliente no está vinculado a su empresa o la relación está deshabilitada (`Acceso no autorizado. Acceso denegado: No tiene permisos para operar sobre esta empresa o la relación no está activa.`), el cliente o la empresa está inactiva (`Acceso no autorizado. La empresa se encuentra inactiva.`) o el usuario no está asociado a una empresa (`Usuario no asociado a ninguna empresa.`)", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Acceso no autorizado. Acceso denegado: No tiene permisos para operar sobre esta empresa o la relación no está activa." } }, "type": "object" } } } }, "404": { "description": "No existe ninguna empresa con ese UUID", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Empresa no encontrada." } }, "type": "object" } } } }, "422": { "description": "`records` ausente o no es un JSON válido. requiere `Accept: application/json`", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "El campo records es requerido" }, "errors": { "type": "object", "example": { "records": [ "El campo records es requerido" ] } } }, "type": "object" } } } }, "429": { "description": "Límite de peticiones por minuto superado (throttle:api)" }, "500": { "description": "Error no controlado. Casos conocidos: `records` es `null` o `false` (`Error interno del servidor. La propiedad RECORDS no está definida.`), se envió el id numérico en vez del UUID (`Error interno del servidor. Debe enviar el UUID del cliente, no el ID.`), falta `records.country_id`, falta `records.dni` con `country_id` 45, o llega `imgdata` sin `imgname`", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Error interno del servidor. La propiedad RECORDS no está definida." }, "reference": { "type": "string", "format": "uuid" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Clientes" ], "summary": "Deshabilitar un cliente (borrado lógico)", "description": "El cliente pasa a listarse con `is_active=0` y la Casa de Software deja de poder operar sobre él (`client_uuid`/`companyId` exigen relación activa). Se revierte con `POST /api/ubl2.1/company/customers/{uuid}/enable`. Deshabilitar un cliente ya deshabilitado responde 200 sin cambios.", "operationId": "deleteCustomer", "parameters": [ { "name": "uuid", "in": "path", "description": "UUID del cliente (sub-cuenta). No se acepta el id numérico.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "client_uuid", "in": "query", "description": "No lo envíe en este endpoint: si se envía, esa empresa pasa a ser la que actúa en lugar de la del token y el `{uuid}` se busca entre sus clientes; si no es cliente de ella, responde 404 sin modificar nada.", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Relación deshabilitada (o sin cambios si ya estaba deshabilitada)", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Cliente eliminado correctamente." }, "success": { "type": "boolean", "example": true } }, "type": "object" } } } }, "401": { "description": "Token ausente, inválido o expirado", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "La empresa del token está inactiva (`Acceso no autorizado. La empresa se encuentra inactiva.`) o el usuario no está asociado a una empresa (`Usuario no asociado a ninguna empresa.`)", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Acceso no autorizado. La empresa se encuentra inactiva." } }, "type": "object" } } } }, "404": { "description": "El UUID no existe o no es un cliente de la empresa del token (mismo mensaje en los dos casos). No se modifica nada", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "El cliente no existe." } }, "type": "object" } } } }, "429": { "description": "Límite de peticiones por minuto superado (throttle:api)" }, "500": { "description": "Error no controlado. Incluye `reference` para ubicar el error en los logs", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Error interno del servidor." }, "reference": { "type": "string", "format": "uuid" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/company/customers/{uuid}/enable": { "post": { "tags": [ "Clientes" ], "summary": "Habilitar un cliente", "description": "Revierte `DELETE /api/ubl2.1/company/customers/{uuid}`. No lleva cuerpo. Habilitar un cliente ya habilitado responde 200.", "operationId": "enableCustomer", "parameters": [ { "name": "uuid", "in": "path", "description": "UUID del cliente (sub-cuenta). No se acepta el id numérico.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "client_uuid", "in": "query", "description": "No lo envíe en este endpoint: si se envía, esa empresa pasa a ser la que actúa en lugar de la del token y el `{uuid}` se busca entre sus clientes; si no es cliente de ella, responde 404 sin modificar nada.", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Cliente habilitado", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Cliente habilitado correctamente." }, "success": { "type": "boolean", "example": true } }, "type": "object" } } } }, "401": { "description": "Token ausente, inválido o expirado", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "La empresa del token está inactiva (`Acceso no autorizado. La empresa se encuentra inactiva.`) o el usuario no está asociado a una empresa (`Usuario no asociado a ninguna empresa.`)", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Acceso no autorizado. La empresa se encuentra inactiva." } }, "type": "object" } } } }, "404": { "description": "El UUID no existe o no es un cliente de la empresa del token (mismo mensaje en los dos casos). No se modifica nada", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "El cliente no existe." } }, "type": "object" } } } }, "429": { "description": "Límite de peticiones por minuto superado (throttle:api)" }, "500": { "description": "Error no controlado. Incluye `reference` para ubicar el error en los logs", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Error interno del servidor." }, "reference": { "type": "string", "format": "uuid" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/company/customers": { "get": { "tags": [ "Clientes" ], "summary": "Listar clientes de la empresa", "description": "El tamaño de página es fijo: 15 registros (`per_page` no es configurable).", "operationId": "listCustomers", "parameters": [ { "name": "is_active", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "enum": [ 0, 1 ] } }, { "name": "search", "in": "query", "description": "Texto a buscar (coincidencia parcial, LIKE) en `dni` o en `company_name`.", "required": false, "schema": { "type": "string" } }, { "name": "uuid", "in": "query", "description": "Filtra por el UUID exacto de un cliente.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "client_uuid", "in": "query", "description": "No lo envíe en este endpoint: si se envía, se listan los clientes de esa empresa en lugar de los de la empresa del token.", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Página de clientes", "content": { "application/json": { "schema": { "properties": { "dataRecords": { "properties": { "current_page": { "type": "integer", "example": 1 }, "data": { "type": "array", "items": { "properties": { "id": { "description": "Id interno", "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "dni": { "type": "string", "example": "900123456" }, "dv": { "type": "string" }, "company_name": { "type": "string", "example": "CLIENTE SAS" }, "trade_name": { "type": "string", "nullable": true }, "email": { "type": "string", "format": "email" }, "country_id": { "type": "integer" }, "city_id": { "type": "integer" }, "identity_document_id": { "type": "integer" }, "type_organization_id": { "type": "integer" }, "tax_regime_id": { "type": "integer" }, "tax_level_id": { "type": "integer" }, "address": { "type": "string" }, "mobile": { "type": "string" }, "phone": { "type": "string" }, "image": { "type": "string", "nullable": true }, "full_path_image": { "description": "URL absoluta del logo, o cadena vacía", "type": "string" }, "software": { "type": "object", "nullable": true }, "certificate": { "type": "object", "nullable": true }, "resolutions": { "type": "array", "items": { "type": "object" } }, "country": { "type": "object", "nullable": true }, "identity_document": { "type": "object", "nullable": true }, "type_organization": { "type": "object" }, "city": { "type": "object", "nullable": true }, "quotas": { "type": "array", "items": { "properties": { "subscription_id": { "type": "integer" }, "consumed_documents": { "type": "integer" }, "assigned_documents": { "type": "integer" } }, "type": "object" } }, "company": { "type": "object" } }, "type": "object" } }, "first_page_url": { "type": "string" }, "from": { "type": "integer", "nullable": true }, "last_page": { "type": "integer" }, "last_page_url": { "type": "string" }, "links": { "type": "array", "items": { "type": "object" } }, "next_page_url": { "type": "string", "nullable": true }, "path": { "type": "string" }, "per_page": { "type": "integer", "example": 15 }, "prev_page_url": { "type": "string", "nullable": true }, "to": { "type": "integer", "nullable": true }, "total": { "type": "integer" } }, "type": "object" }, "success": { "type": "boolean", "example": true } }, "type": "object" } } } }, "401": { "description": "Token ausente, inválido o expirado", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "La empresa del token está inactiva", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "La empresa se encuentra inactiva." } }, "type": "object" } } } }, "429": { "description": "Límite de peticiones por minuto superado (throttle:api)" }, "500": { "description": "también cuando el usuario no está asociado a una empresa", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Server Error" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/company": { "get": { "tags": [ "Empresa" ], "summary": "Obtener información de la empresa", "operationId": "056d1eb631a4c9bc917a338efaad7b3f", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Información de la empresa obtenida exitosamente" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/company/{uuid}": { "put": { "tags": [ "Empresa" ], "summary": "Actualizar información de la empresa", "operationId": "f4a10fe694631dcb2c1c5738c12a9cf3", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string" }, "nit": { "type": "string" }, "email": { "type": "string", "format": "email" } }, "type": "object" } } } }, "responses": { "200": { "description": "Empresa actualizada exitosamente" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/company/{uuid}/image": { "put": { "tags": [ "Empresa" ], "summary": "Actualizar el logo de la empresa o de un cliente", "description": "También disponible bajo `/api/ubl2.1/company/customers/{uuid}/image` para actualizar el logo de un cliente de la Casa de Software.", "operationId": "a3f16a0a665ed536f99fad127d56ce18", "parameters": [ { "name": "uuid", "in": "path", "description": "UUID de la empresa o del cliente", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "description": "JSON string con la imagen en base64", "required": true, "content": { "application/json": { "schema": { "required": [ "records" ], "properties": { "records": { "description": "JSON string con `imgdata` (base64, con prefijo data URI) e `imgname` (nombre del archivo)", "type": "string", "format": "json", "example": "{\"imgdata\":\"data:image/png;base64,iVBORw0KGgo...\",\"imgname\":\"logo.png\"}" } }, "type": "object" } } } }, "responses": { "200": { "description": "Imagen actualizada exitosamente" }, "404": { "description": "Empresa no encontrada o propiedad IMGDATA no definida" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/company/customers/{uuid}/image": { "put": { "tags": [ "Clientes" ], "summary": "Actualizar el logo de un cliente", "description": "El cuerpo lleva `records`: un **string JSON** con `imgdata` (data URI en base64; se toma lo que sigue a la primera coma) e `imgname` (solo se usa su extensión: png, jpg, jpeg, gif, webp, svg, jfif, bmp o ico; cualquier otra se guarda como png). No hay validación previa del cuerpo. Cualquier otro atributo editable incluido en `records` también se aplica. El cambio queda auditado.", "operationId": "updateCustomerImage", "parameters": [ { "name": "uuid", "in": "path", "description": "UUID del cliente (sub-cuenta). No se acepta el id numérico.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "client_uuid", "in": "query", "description": "Se ignora: el cliente sobre el que se opera es siempre el del `{uuid}` de la ruta.", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "records" ], "properties": { "records": { "description": "String JSON con `imgdata` e `imgname`", "type": "string", "format": "json", "example": "{\"imgdata\":\"data:image/png;base64,iVBORw0KGgo...\",\"imgname\":\"logo.png\"}" } }, "type": "object" } } } }, "responses": { "200": { "description": "Logo actualizado.", "content": { "application/json": { "schema": { "properties": { "dataRecords": { "type": "object" }, "message": { "type": "string", "example": "Imagen actualizada correctamente." }, "success": { "type": "boolean", "example": true } }, "type": "object" } } } }, "401": { "description": "Token ausente, inválido o expirado", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "El cliente no está vinculado a su empresa o la relación está deshabilitada (`Acceso no autorizado. Acceso denegado: No tiene permisos para operar sobre esta empresa o la relación no está activa.`), el cliente o la empresa está inactiva (`Acceso no autorizado. La empresa se encuentra inactiva.`) o el usuario no está asociado a una empresa (`Usuario no asociado a ninguna empresa.`)", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Acceso no autorizado. Acceso denegado: No tiene permisos para operar sobre esta empresa o la relación no está activa." } }, "type": "object" } } } }, "404": { "description": "No existe ninguna empresa con ese UUID (`Empresa no encontrada.`), falta `imgdata` en `records` (`La propiedad IMGDATA no está definida.`) o `imgdata` no tiene contenido después de la coma (`La propiedad IMGDATA no está definida o está vacía.`)", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "La propiedad IMGDATA no está definida." } }, "type": "object" } } } }, "429": { "description": "Límite de peticiones por minuto superado (throttle:api)" }, "500": { "description": "Error no controlado. Casos conocidos: `records` ausente o no es JSON (`Error interno del servidor. La propiedad RECORDS no está definida.`), se envió el id numérico en vez del UUID (`Error interno del servidor. Debe enviar el UUID del cliente, no el ID.`) o falta `imgname`", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Error interno del servidor. La propiedad RECORDS no está definida." }, "reference": { "type": "string", "format": "uuid" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/company/customers/{uuid}/stats": { "get": { "tags": [ "Clientes" ], "summary": "Obtener estadísticas de un cliente específico de la Casa de Software", "description": "Solo lectura. `subscription` es `null` si no se resuelve ninguna membresía. Según de dónde venga: cuota asignada al cliente => `plan_name` = `Cuota Asignada` y `total_documents_limit` = documentos asignados; membresía heredada del padre sin cuota propia => `plan_name` = `CUENTA MAESTRA` y `total_documents_limit` = 0 (no expone el límite del padre); membresía propia => nombre y límite del plan.", "operationId": "customerStats", "parameters": [ { "name": "uuid", "in": "path", "description": "UUID del cliente a consultar", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "client_uuid", "in": "query", "description": "No lo envíe en este endpoint: si se envía, el cliente del `{uuid}` se busca entre los clientes de esa empresa y no entre los de la empresa del token.", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Estadísticas del cliente", "content": { "application/json": { "schema": { "properties": { "dataRecords": { "properties": { "customer": { "properties": { "id": { "description": "Id interno", "type": "integer" }, "dni": { "type": "string", "example": "900123456" }, "dv": { "type": "string" }, "company_name": { "type": "string", "example": "CLIENTE SAS" }, "email": { "type": "string", "format": "email" }, "city": { "description": "Nombre de la ciudad", "type": "string", "nullable": true } }, "type": "object" }, "stats": { "properties": { "total_documents_consumed": { "type": "integer" }, "total_storage_bytes": { "type": "integer" }, "total_storage_mb": { "description": "Mismo valor en MB, con 2 decimales", "type": "number", "format": "float", "example": 1.25 } }, "type": "object" }, "subscription": { "properties": { "id": { "type": "integer" }, "status": { "type": "string", "example": "active" }, "start_date": { "type": "string" }, "end_date": { "type": "string" }, "total_documents_limit": { "type": "integer" }, "plan_name": { "type": "string", "example": "CUENTA MAESTRA" }, "is_unlimited": { "type": "boolean" } }, "type": "object", "nullable": true } }, "type": "object" }, "success": { "type": "boolean", "example": true } }, "type": "object" } } } }, "401": { "description": "Token ausente, inválido o expirado", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "La empresa del token está inactiva. El mensaje no lleva el prefijo `Acceso no autorizado.`", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "La empresa se encuentra inactiva." }, "success": { "type": "boolean", "example": false } }, "type": "object" } } } }, "404": { "description": "El cliente no existe o no está vinculado a la empresa del token", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Cliente no encontrado." }, "success": { "type": "boolean", "example": false } }, "type": "object" } } } }, "429": { "description": "Límite de peticiones por minuto superado (throttle:api)" }, "500": { "description": "Cualquier otro error, incluido el usuario no asociado a una empresa. No incluye `reference`", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Error interno del servidor." }, "success": { "type": "boolean", "example": false } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/company/{uuid}/customer": { "post": { "tags": [ "Clientes" ], "summary": "Crear un nuevo cliente (sub-cuenta) para una empresa desarrolladora", "description": "Crea, en una sola transacción, el usuario y la empresa del cliente y los vincula a la empresa del token. Es el único endpoint que crea sub-cuentas (`POST /api/ubl2.1/register` las rechaza). `{uuid}` debe ser la empresa propia del usuario autenticado, activa, y su titular debe ser un usuario DESARROLLADOR. En producción, la empresa padre no puede tener plan FREE (en sandbox no aplica). No se aplica un límite de número de clientes. El usuario se crea siempre como CLIENT: `type_id` del cuerpo se ignora. Nombres y razón social se guardan en mayúsculas y el `dv` se calcula a partir del `dni`. El cliente recibe su propia suscripción plan FREE (100 documentos, 1 año), también en sandbox. El correo queda verificado y no se envía ningún correo; el cliente ya puede iniciar sesión. La validación del cuerpo (422) se ejecuta antes de comprobar el `{uuid}`. El plan FREE y el titular que no es DESARROLLADOR se comprueban antes de crear nada y responden 403. La respuesta trae el `uuid` y el `id` del cliente.", "operationId": "storeCustomer", "parameters": [ { "name": "uuid", "in": "path", "description": "UUID de la empresa padre (la empresa propia del desarrollador autenticado)", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "client_uuid", "in": "query", "description": "Se ignora: la empresa padre es siempre el `{uuid}` de la ruta.", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "first_name", "last_name", "company_name", "email", "password", "password_confirmation", "dni" ], "properties": { "first_name": { "type": "string", "maxLength": 100, "example": "Juan" }, "last_name": { "type": "string", "maxLength": 100, "example": "Pérez" }, "company_name": { "type": "string", "maxLength": 100, "example": "Cliente SAS" }, "trade_name": { "description": "Nombre comercial. Opcional; se guarda tal como llega (sin pasar a mayúsculas)", "type": "string", "maxLength": 250, "example": "Cliente Express", "nullable": true }, "email": { "description": "Único en `users`. Se valida el formato RFC y que el dominio tenga DNS", "type": "string", "format": "email", "maxLength": 255, "example": "cliente@empresa.com" }, "password": { "type": "string", "format": "password", "minLength": 8 }, "password_confirmation": { "description": "Debe coincidir con `password`", "type": "string", "format": "password" }, "dni": { "description": "NIT o documento, solo dígitos (sin `dv`, puntos, guiones ni letras) y máximo 15. Único en `companies`. Con cualquier otro carácter responde 422 (`El NIT debe contener solo dígitos, sin puntos, guiones ni dígito de verificación`); con más de 15 dígitos, 422 (`El NIT no puede tener más de 15 dígitos`)", "type": "string", "maxLength": 15, "pattern": "^[0-9]+$", "example": "900123456" }, "country_id": { "description": "No se valida; un id inexistente responde 400 con el mensaje de la base de datos", "type": "integer", "default": 45 }, "city_id": { "description": "No se valida; un id inexistente responde 400 con el mensaje de la base de datos", "type": "integer", "default": 149 }, "identity_document_id": { "type": "integer", "default": 3 }, "type_organization_id": { "type": "integer", "default": 1 }, "tax_regime_id": { "type": "integer", "default": 1 }, "tax_level_id": { "type": "integer", "default": 5 }, "address": { "type": "string", "example": "Calle 123" }, "location": { "type": "string" }, "postal_code": { "type": "string" }, "mobile": { "type": "string", "example": "3001234567" }, "phone": { "type": "string", "example": "6012345678" }, "web": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Cliente creado. Se responde 200, no 201. `dataRecords` es la empresa recién creada tal como quedó en la base de datos (todas sus columnas, más `full_path_image`): incluye el `uuid` que usan los endpoints `/company/customers/{uuid}` y el `client_uuid` de las cuotas, y el `id` interno", "content": { "application/json": { "schema": { "properties": { "dataRecords": { "properties": { "id": { "description": "Id interno. Las cuotas identifican al cliente por su `uuid` (`client_uuid`)", "type": "integer" }, "uuid": { "description": "UUID del cliente para `/company/customers/{uuid}`", "type": "string", "format": "uuid" }, "country_id": { "type": "integer", "example": 45 }, "city_id": { "type": "integer", "example": 149 }, "identity_document_id": { "type": "integer", "example": 3 }, "type_organization_id": { "type": "integer", "example": 1 }, "tax_regime_id": { "type": "integer", "example": 1 }, "tax_level_id": { "type": "integer", "example": 5 }, "company_name": { "type": "string", "example": "CLIENTE SAS" }, "trade_name": { "type": "string", "example": "Cliente Express", "nullable": true }, "dni": { "type": "string", "example": "900123456" }, "dv": { "type": "string" }, "address": { "type": "string" }, "location": { "type": "string" }, "postal_code": { "type": "string" }, "mobile": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string", "format": "email" }, "web": { "type": "string" }, "full_path_image": { "type": "string", "example": "" } }, "type": "object" }, "message": { "type": "string", "example": "Cliente creado con éxito, ya puede iniciar sesión. No es necesario verificar el correo electrónico." }, "success": { "type": "boolean", "example": true } }, "type": "object" } } } }, "400": { "description": "Un valor viola una restricción de integridad de la base de datos (por ejemplo, `country_id` o `city_id` inexistente). El `message` es el de la base de datos. No se crea nada (rollback)", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Token ausente, inválido o expirado", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "`{uuid}` es otra empresa (`Acceso no autorizado. Acceso denegado: Solo puede crear clientes en su propia empresa.`), la empresa padre está inactiva (`Acceso no autorizado. La empresa se encuentra inactiva.`), el usuario del token o el titular de la empresa padre no está asociado a una empresa (`Usuario no asociado a ninguna empresa.`), la empresa padre tiene plan FREE (`El plan FREE no permite agregar clientes. Actualice su plan para acceder a esta funcionalidad.`, solo en producción) o su titular no es DESARROLLADOR (`Solo los usuarios DESARROLLADORES pueden crear clientes.`). Estos dos últimos se comprueban antes de crear nada", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Acceso no autorizado. Acceso denegado: Solo puede crear clientes en su propia empresa." } }, "type": "object" } } } }, "404": { "description": "No existe ninguna empresa con ese UUID (`Empresa no encontrada.`) o no existe el usuario titular de la empresa padre (`Usuario no encontrado.`)", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Empresa no encontrada." } }, "type": "object" } } } }, "422": { "description": "Errores de validación. requiere `Accept: application/json`. Mensajes propios: `El nombre es requerido`, `El apellido es requerido`, `El nombre de la empresa es requerido`, `El correo electrónico es requerido`, `El correo electrónico no es válido o su dominio no existe`, `El correo electrónico ya existe`, `El NIT es requerido`, `El NIT ya existe`, `El NIT debe contener solo dígitos, sin puntos, guiones ni dígito de verificación`, `El NIT no puede tener más de 15 dígitos` (las reglas de `password`, `max` y `string` usan los mensajes del framework)", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "El correo electrónico ya existe" }, "errors": { "type": "object", "example": { "email": [ "El correo electrónico ya existe" ] } } }, "type": "object" } } } }, "429": { "description": "Límite de peticiones por minuto superado (throttle:api)" }, "500": { "description": "Cualquier otro error en la creación; no se crea nada (rollback)", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Error interno del servidor. ..." }, "reference": { "type": "string", "format": "uuid" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/currency": { "get": { "tags": [ "Monedas" ], "summary": "Obtener moneda específica", "operationId": "2ba4c5af1f4b77cca9096dc9c30adf2f", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Moneda obtenida exitosamente" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Monedas" ], "summary": "Crear nueva moneda", "operationId": "273140f2c373553036504a2d02e908aa", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "code": { "type": "string", "example": "USD" }, "name": { "type": "string", "example": "Dólar Estadounidense" }, "symbol": { "type": "string", "example": "$" } }, "type": "object" } } } }, "responses": { "201": { "description": "Moneda creada exitosamente" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/currency/all": { "get": { "tags": [ "Monedas" ], "summary": "Listar todas las monedas", "operationId": "ebdc690bedd1fd4a6b96268dba1f6f99", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Lista de monedas obtenida exitosamente", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/currency/{id}": { "put": { "tags": [ "Monedas" ], "summary": "Actualizar moneda", "operationId": "039ce0e86dd72c71e1369638dfe20279", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Moneda actualizada exitosamente" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Monedas" ], "summary": "Eliminar moneda", "operationId": "7ac79fb038a2397fbd10131e8ec461d0", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Moneda eliminada exitosamente" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/currency/change/local": { "get": { "tags": [ "Monedas" ], "summary": "Obtener tasa de cambio local", "operationId": "4a28f6cbb3e804fa23274e2ab99a6d81", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Tasa de cambio local obtenida exitosamente" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/currency/change": { "get": { "tags": [ "Monedas" ], "summary": "Obtener tasa de cambio", "operationId": "fe6a871f2d8363225a84556d70137bd3", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Tasa de cambio obtenida exitosamente" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/documents/{uuid}/resend": { "post": { "tags": [ "Gestión de Documentos" ], "summary": "Reenviar documento rechazado", "operationId": "e7c0a69aba6a682a8ac782eb292dea48", "parameters": [ { "name": "uuid", "in": "path", "description": "UUID del documento", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Documento reenviado exitosamente" }, "404": { "description": "Documento no encontrado" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/documents/sendmail/to": { "post": { "tags": [ "Gestión de Documentos" ], "summary": "Enviar múltiples documentos por correo", "operationId": "727dcf3472ae3ee33654c638333d40d2", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "email_to": { "description": "Correo(s) del destinatario, separados por coma", "type": "string", "example": "cliente@example.com" }, "subject": { "description": "Asunto del correo", "type": "string", "example": "Documentos electrónicos" }, "title": { "description": "Título del correo", "type": "string", "example": "Documentos adjuntos" }, "message": { "description": "Mensaje del correo", "type": "string", "example": "Adjuntamos los documentos solicitados" }, "documents": { "type": "array", "items": { "properties": { "name": { "type": "string" }, "content": { "type": "string", "format": "byte" }, "mime": { "type": "string" } }, "type": "object" } }, "attachments": { "$ref": "#/components/schemas/UserAttachments" } }, "type": "object" } } } }, "responses": { "200": { "description": "Correos enviados exitosamente" }, "413": { "description": "Cuota de almacenamiento excedida" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/documents/sendmail/{trackId}": { "post": { "tags": [ "Gestión de Documentos" ], "summary": "Enviar documento específico por correo", "operationId": "07c958e853ffa375a7da37c4081cd9f8", "parameters": [ { "name": "trackId", "in": "path", "description": "Track ID del documento", "required": true, "schema": { "type": "string" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "email": { "type": "string", "format": "email", "example": "cliente@example.com" } }, "type": "object" } } } }, "responses": { "200": { "description": "Correo enviado exitosamente" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/documents/pdf/{trackId}": { "post": { "tags": [ "Gestión de Documentos" ], "summary": "Obtener PDF de un documento", "operationId": "e889e6b926206c6ad50fa43971e07ac5", "parameters": [ { "name": "trackId", "in": "path", "description": "Track ID del documento", "required": true, "schema": { "type": "string" } }, { "name": "regenerate", "in": "query", "description": "Regenerar PDF (0=usar caché, 1=regenerar)", "schema": { "type": "integer", "default": 0, "enum": [ 0, 1 ] } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "PDF generado exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" }, "pdf": { "properties": { "path": { "type": "string" }, "outputName": { "type": "string" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/documents/xml/{trackId}": { "get": { "tags": [ "Gestión de Documentos" ], "summary": "Obtener XML de un documento (Solo planes pagos)", "operationId": "f3b10c610a365bfd43db2579951b94c3", "parameters": [ { "name": "trackId", "in": "path", "description": "Track ID del documento", "required": true, "schema": { "type": "string" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "XML obtenido exitosamente", "content": { "application/xml": {} } }, "403": { "description": "Funcionalidad bloqueada en plan FREE" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/documents/attached/{trackId}": { "post": { "tags": [ "Gestión de Documentos" ], "summary": "Obtener archivos adjuntos de un documento", "operationId": "da607171016b233cd3f375d3a000d17b", "parameters": [ { "name": "trackId", "in": "path", "description": "Track ID del documento", "required": true, "schema": { "type": "string" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Archivos adjuntos obtenidos exitosamente" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/events/send/mail/{trackId}": { "post": { "tags": [ "Eventos de Documentos" ], "summary": "Reenviar correo de evento a la DIAN", "operationId": "97d7f8bf6b12094d32c2e737917dabc7", "parameters": [ { "name": "trackId", "in": "path", "description": "id numérico del evento (el id de events en GET /api/ubl2.1/events/document-receptions/{documentId} o el event_id de send-bulk), no el CUFE/CUDE", "required": true, "schema": { "type": "integer", "example": 4521 } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Correo enviado", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Correo enviado correctamente" }, "success": { "type": "boolean", "example": true } } } } } }, "400": { "description": "Se alcanzó el límite de 4 correos por evento", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Se ha alcanzado el límite de envío de correos. No puede enviar más de 4 correos por evento." } } } } } }, "403": { "$ref": "#/components/responses/ReceptionNotInPlan" }, "404": { "description": "El evento no existe o es de otra empresa (misma respuesta)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "El evento no existe." } } } } } } }, "security": [ { "bearerAuth": [] } ], "description": "Reenvía el correo de un evento RADIAN ya registrado. Máximo 4 correos por evento. Exige plan de pago vigente (403 RECEPTION_NOT_IN_PLAN, antes que cualquier otra validación)." } }, "/api/ubl2.1/events/send/{trackId}": { "post": { "tags": [ "Eventos de Documentos" ], "summary": "Enviar evento RADIAN sobre un documento recibido", "description": "Registra y transmite a la DIAN, en el momento, un evento RADIAN (acuse de recibo, reclamo, recibo del bien, aceptación) sobre un documento previamente recibido. Sale siempre, también si la empresa está en modo manual. Si el documento ya tiene ese evento (en cualquier numeración) se reutiliza en lugar de crear otro. Cuando `code=031` (Reclamo de la Factura Electrónica de Venta), el campo `claim_code` es obligatorio y debe ser un código válido del catálogo de motivos de reclamo de la DIAN. Firma la persona indicada en `reception_person_uuid` o, sin ella, la persona de recepción por defecto de la empresa.", "operationId": "5219715d285287cb9f87eecfe55a5475", "parameters": [ { "name": "trackId", "in": "path", "description": "Track ID del documento", "required": true, "schema": { "type": "string" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventRequest" } } } }, "responses": { "200": { "description": "Evento enviado exitosamente" }, "400": { "description": "El tipo de evento no existe, el código de reclamación es obligatorio (code=031), el código de reclamación no existe, la empresa no tiene persona de recepción, el evento ya fue aceptado o el documento no admite eventos (contado o sin medio de pago, nota crédito/débito u omitido; el mensaje dice el motivo)" }, "403": { "$ref": "#/components/responses/ReceptionNotInPlan" }, "404": { "description": "reception_person_uuid no existe, fue eliminada o es de otra empresa" }, "409": { "description": "El evento ya se está enviando (lo tiene el programador, un envío en bloque u otra petición). No se envía en paralelo; si el envío en curso falla, el evento se puede volver a enviar" }, "422": { "description": "reception_person_uuid no es un UUID válido" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/events/send-bulk": { "post": { "tags": [ "Eventos de Documentos" ], "summary": "Enviar el acuse de recibo (030) a varias recepciones", "description": "Envío EN BLOQUE pedido por el usuario. Por cada recepción indicada crea (o reutiliza) el evento 030 y encola su envío a la DIAN; sale siempre, también si la empresa está en modo manual. Es idempotente: un 030 ya aceptado o en envío no se vuelve a enviar, y nunca se crea un segundo 030 para el mismo documento. Un 030 RECHAZADO o CANCELADO se reenvía, igual que en el envío individual. El envío es asíncrono: `queued` significa encolado, no aceptado; el estado final se ve en GET /events/document-receptions/{documentId}. Firma la persona indicada en `reception_person_uuid` o, sin ella, la persona de recepción por defecto. Acepta `client_uuid` (sub-cuenta propia) como el resto de eventos.", "operationId": "0456af79b6597009506b3952ad16775f", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "document_ids", "code" ], "properties": { "document_ids": { "description": "Los repetidos se envían una sola vez.", "type": "array", "items": { "type": "integer", "example": 123 }, "maxItems": 50, "minItems": 1 }, "code": { "description": "Código del evento. En bloque solo el acuse de recibo.", "type": "string", "enum": [ "030" ], "example": "030" }, "reception_person_uuid": { "description": "Persona que firma; sin ella, la persona por defecto", "type": "string", "format": "uuid", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Resultado por documento", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Envío en bloque procesado." }, "summary": { "properties": { "requested": { "type": "integer", "example": 3 }, "queued": { "type": "integer", "example": 1 }, "already_exists": { "type": "integer", "example": 1 }, "not_applicable": { "type": "integer", "example": 1 }, "not_found": { "type": "integer", "example": 0 }, "error": { "type": "integer", "example": 0 } }, "type": "object" }, "results": { "type": "array", "items": { "properties": { "document_id": { "type": "integer" }, "folio": { "type": "string", "nullable": true }, "status": { "description": "queued: encolado; already_exists: el 030 ya está aceptado o en envío; not_applicable: no admite eventos (contado, nota, omitido, en proceso o fallido; ver message); not_found: no es de la empresa; error: no se pudo encolar", "type": "string", "enum": [ "queued", "already_exists", "not_applicable", "not_found", "error" ] }, "message": { "type": "string" }, "event_id": { "type": "integer", "nullable": true }, "document_status": { "type": "string", "example": "PROCESSING", "nullable": true } }, "type": "object" } } }, "type": "object" } } } }, "400": { "description": "La empresa no tiene persona de recepción o numeración activa de eventos" }, "403": { "$ref": "#/components/responses/ReceptionNotInPlan" }, "404": { "description": "reception_person_uuid ajeno o eliminado, o ninguna de las recepciones es de la empresa" }, "422": { "description": "document_ids vacío, con más elementos que el máximo o no enteros; code distinto de 030; reception_person_uuid mal formado" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/events/document-receptions": { "get": { "tags": [ "Eventos de Documentos" ], "summary": "Listar recepciones de documentos", "operationId": "65f8ffb98da663ed75197388372a0577", "parameters": [ { "name": "query", "in": "query", "description": "Búsqueda por nombre o NIT del emisor", "required": false, "schema": { "type": "string" } }, { "name": "startDate", "in": "query", "description": "Fecha inicial del rango (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "endDate", "in": "query", "description": "Fecha final del rango (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "trackId", "in": "query", "description": "Filtrar por CUFE/CUDE específico", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Registros por página (máximo 50, default 20)", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 50 } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Lista de recepciones obtenida exitosamente", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "403": { "$ref": "#/components/responses/ReceptionNotInPlan" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/events/document-receptions/{documentId}": { "get": { "tags": [ "Eventos de Documentos" ], "summary": "Obtener eventos por ID de documento", "operationId": "a974b7b895446a1f1d009c10d82a37c8", "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Eventos obtenidos exitosamente" }, "403": { "$ref": "#/components/responses/ReceptionNotInPlan" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/events/status/{trackId}": { "get": { "tags": [ "Eventos de Documentos" ], "summary": "Obtener estado del evento", "operationId": "43f72e2fd1a403ea582bb67dbe46b8da", "parameters": [ { "name": "trackId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Estado del evento obtenido" }, "403": { "$ref": "#/components/responses/ReceptionNotInPlan" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/events/import-excel": { "post": { "tags": [ "Eventos de Documentos" ], "summary": "Importar eventos desde Excel", "operationId": "857b480b1bf1e0a3dd57d843c8540031", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "document_base64": { "description": "Archivo Excel (.xlsx/.xls) codificado en base64", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Eventos importados exitosamente" }, "403": { "$ref": "#/components/responses/ReceptionNotInPlan" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/events/import-track-id": { "post": { "tags": [ "Eventos de Documentos" ], "summary": "Importar evento por Track ID", "operationId": "36e0f9696cb96c78f5a4b771e1100f15", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "trackId": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Evento importado exitosamente" }, "403": { "$ref": "#/components/responses/ReceptionNotInPlan" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/events/{trackId}/import": { "post": { "tags": [ "Eventos de Documentos" ], "summary": "Importar evento por Track ID (alternativo)", "operationId": "aee88609cf47ddfd797333eebcca50eb", "parameters": [ { "name": "trackId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Evento importado exitosamente" }, "403": { "$ref": "#/components/responses/ReceptionNotInPlan" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/events/document-receptions/{id}": { "delete": { "tags": [ "Eventos de Documentos" ], "summary": "Eliminar recepción de documento", "operationId": "bc21a25861be36995ebd4482cba7f442", "parameters": [ { "name": "id", "in": "path", "description": "ID de la recepción de documento", "required": true, "schema": { "type": "integer" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Recepción eliminada exitosamente" }, "403": { "$ref": "#/components/responses/ReceptionNotInPlan" }, "404": { "description": "Recepción no encontrada" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/events/{id}/cancel": { "post": { "tags": [ "Eventos de Documentos" ], "summary": "Cancelar un evento pendiente de envío a la DIAN", "description": "Cancela un evento (030/031/032/033) que aún se encuentra en estado PENDING. Una vez el evento pasa a PROCESSING (recogido por el job programado que lo transmite a la DIAN) ya no puede cancelarse.", "operationId": "71766f84270a08d97b40265c56bcfc60", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Evento cancelado exitosamente" }, "400": { "description": "El evento no está en estado PENDING" }, "403": { "$ref": "#/components/responses/ReceptionNotInPlan" }, "404": { "description": "Evento no encontrado" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/events/document-receptions/{documentId}/files": { "get": { "tags": [ "Eventos de Documentos" ], "summary": "Listar archivos de una recepción de documento (buzón)", "description": "Lista los archivos con custodia vinculados a una recepción de documento recibida por el buzón (Nivel 2): el correo crudo (INBOUND_EMAIL_RAW), el XML del documento y el ZIP adjunto. Las recepciones importadas por Excel o por CUFE no tienen archivos vinculados y devuelven una lista vacía.", "operationId": "f8b62b6b98ffb24765c96e199bcb0d20", "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Archivos listados exitosamente", "content": { "application/json": { "schema": { "properties": { "dataRecords": { "properties": { "data": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "type_document": { "type": "string", "enum": [ "INBOUND_EMAIL_RAW", "XML", "ZIP" ] }, "file_name": { "type": "string" }, "mime_type": { "type": "string" }, "file_size": { "description": "Tamaño en bytes", "type": "integer", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "403": { "$ref": "#/components/responses/ReceptionNotInPlan" }, "404": { "description": "Recepción de documento no encontrada" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/events/document-receptions/{documentId}/files/{fileManagerId}/download": { "get": { "tags": [ "Eventos de Documentos" ], "summary": "Descargar un archivo de una recepción de documento (buzón)", "description": "Descarga el contenido real (XML/ZIP/PDF/correo crudo) de un archivo vinculado a una recepción de documento, verificando que pertenezca a la empresa autenticada.", "operationId": "ba684bf21e7d41e410778e7b084a1bb4", "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "fileManagerId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Archivo descargado exitosamente" }, "403": { "$ref": "#/components/responses/ReceptionNotInPlan" }, "404": { "description": "Recepción o archivo no encontrado" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/documents/{uuid}": { "get": { "tags": [ "Documentos Enviados" ], "summary": "Obtener documento por UUID", "operationId": "def58a0d13077ac200c8b792d8b1bda2", "parameters": [ { "name": "uuid", "in": "path", "description": "UUID del documento", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Documento obtenido exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Documento no encontrado" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/documents/{uuid}/files": { "get": { "tags": [ "Documentos Enviados" ], "summary": "Obtener archivos de un documento por UUID", "operationId": "ce4f3d7ec9783552bc3efe95a37c6e71", "parameters": [ { "name": "uuid", "in": "path", "description": "UUID del documento", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Archivos obtenidos exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Documento no encontrado" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/documents/consume": { "get": { "tags": [ "Documentos Enviados" ], "summary": "Obtener consumo de documentos", "description": "Documentos validados por la DIAN (is_valid = 1) del año, agrupados según p_type. Los totales cuentan documentos válidos, no el consumo cobrado de la membresía.", "operationId": "b944c0ae3601d798df3fed71ee2f5939", "parameters": [ { "name": "p_type", "in": "query", "description": "1: por mes y tipo de documento (empresa y sus clientes). 2: por año (empresa y sus clientes). 3: por cliente y mes. 4: por cliente y año. 6: un cliente (_dni) por mes y tipo de documento.", "schema": { "type": "integer", "default": 1, "enum": [ 1, 2, 3, 4, 6 ] } }, { "name": "p_year", "in": "query", "description": "Año (por defecto, el actual)", "schema": { "type": "integer", "example": 2026 } }, { "name": "_dni", "in": "query", "description": "NIT del cliente (sin dígito de verificación). Obligatorio con p_type=6. También se acepta como p_dni.", "schema": { "type": "string", "example": "901091403" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Consumo obtenido exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" }, "dataRecords": { "properties": { "data": { "description": "Filas del consumo; las columnas dependen de p_type", "type": "array", "items": { "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "p_type, p_year o _dni inválidos (p_type=6 sin _dni)" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/documents/last": { "get": { "tags": [ "Documentos Enviados" ], "summary": "Obtener último documento enviado", "operationId": "a611a2c254171dc6d44ef4cdbe09e7fc", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Último documento obtenido exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/documents": { "get": { "tags": [ "Documentos Enviados" ], "summary": "Listar documentos enviados", "operationId": "0c10c8a380a7a19cd0b040589167a62e", "parameters": [ { "name": "page", "in": "query", "description": "Número de página", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "description": "Documentos por página", "schema": { "type": "integer", "default": 15 } }, { "name": "start_date", "in": "query", "description": "Fecha de inicio", "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "description": "Fecha de fin", "schema": { "type": "string", "format": "date" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Lista de documentos obtenida exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object" } }, "meta": { "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/documents/{id}": { "delete": { "tags": [ "Documentos Enviados" ], "summary": "Eliminar documento", "description": "Solo elimina documentos que la DIAN no tiene: sin validar (0) o no encontrados/rechazados en la revalidación (3), sin clave transmitida o con un rechazo de la DIAN guardado para esa misma clave. Un 98 (en validación), la regla 90 o una clave sin respuesta definitiva no se eliminan.", "operationId": "95d62a72b6801f7a4df7f3f9f52b6a30", "parameters": [ { "name": "id", "in": "path", "description": "ID del documento", "required": true, "schema": { "type": "integer" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Documento eliminado exitosamente" }, "400": { "description": "El documento está validado o la DIAN podría tenerlo; no se eliminó" }, "404": { "description": "Documento no encontrado" }, "409": { "description": "code DOCUMENT_IN_TRANSMISSION: el número se está transmitiendo a la DIAN, o el documento cambió mientras se eliminaba" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/settings/email-branding": { "get": { "tags": [ "Personalización de Correos" ], "summary": "Ver la personalización de correos", "description": "Devuelve la configuración de los tres tipos de correo (INVOICE, EVENT, CUSTOM) de la empresa autenticada, con las variables permitidas en cada uno. Los tipos sin configurar usan el diseño de la plataforma.", "operationId": "bec377f31d354580f42cf691a589d5d6", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Configuración obtenida", "content": { "application/json": { "schema": { "properties": { "dataRecords": { "properties": { "data": { "type": "array", "items": { "properties": { "email_type": { "type": "string", "enum": [ "INVOICE", "EVENT", "CUSTOM" ] }, "configured": { "description": "false = usa el diseño de la plataforma", "type": "boolean" }, "is_active": { "type": "boolean" }, "logo_asset_id": { "type": "integer", "nullable": true }, "logo_url": { "description": "URL del logo aplicable; el de la plataforma si no hay uno propio", "type": "string" }, "inherited": { "description": "true si la configuración proviene de la casa de software", "type": "boolean" }, "editable": { "description": "false en sub-cuentas: solo el desarrollador configura", "type": "boolean" }, "applied_on_send": { "description": "si esta configuración se aplica realmente al enviar", "type": "boolean" }, "properties": { "description": "Ajustes visuales agrupados: primary_color, secondary_color, border_color", "type": "object", "nullable": true }, "primary_color": { "description": "Copia plana de properties.primary_color", "type": "string", "example": "#1A73E8", "nullable": true }, "secondary_color": { "description": "Copia plana de properties.secondary_color", "type": "string", "nullable": true }, "border_color": { "description": "Copia plana de properties.border_color", "type": "string", "nullable": true }, "greeting_text": { "description": "HTML saneado", "type": "string", "nullable": true }, "body_text": { "description": "HTML saneado", "type": "string", "nullable": true }, "footer_text": { "description": "HTML saneado", "type": "string", "nullable": true }, "subject_template": { "description": "Texto plano siempre: es una cabecera de correo", "type": "string", "nullable": true }, "allowed_variables": { "description": "Nombres admitidos para este tipo", "type": "array", "items": { "type": "string" } }, "variables": { "description": "Catálogo explicado de las variables, para mostrarlas en el panel sin que el desarrollador tenga que adivinar a qué se refiere cada una", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "recipient_name" }, "description": { "type": "string", "example": "Nombre del cliente que recibe el documento" }, "group": { "type": "string", "example": "Datos de quien recibe" }, "example": { "type": "string", "example": "CLIENTE DE EJEMPLO S.A.S." } }, "type": "object" } }, "subject_editable": { "description": "Solo CUSTOM: en factura y eventos el asunto lo fija la DIAN", "type": "boolean" } }, "type": "object" } }, "inherited_by": { "description": "true si esta empresa tiene clientes que heredan su personalización", "type": "boolean" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/settings/email-branding/{type}": { "put": { "tags": [ "Personalización de Correos" ], "summary": "Guardar la personalización de un tipo de correo", "description": "Guarda los colores y textos de un tipo de correo. El logo se sube aparte (POST .../logo). Los clientes de la casa de software heredan esta configuración. Los textos admiten variables {{variable}} de la lista permitida para ese tipo (ver el catálogo `variables` que devuelve GET email-branding). El asunto solo es editable en CUSTOM: en factura y eventos lo fija el formato exigido por la DIAN. * * Los tres textos aceptan HTML de un editor enriquecido. La API lo sanea antes de guardar, de modo que lo almacenado es exactamente lo que se enviará. Etiquetas admitidas: p, br, b, strong, i, em, u, s, span[style], a[href|title|target], ul, ol, li, h3, h4, blockquote. En style solo color, font-weight, font-style, text-decoration y text-align. Todo lo demás se descarta: scripts, imágenes, iframes, href javascript: y manejadores de eventos. El marcado mal cerrado se repara. Los saltos de línea escritos en un textarea se conservan como
.", "operationId": "3b4dde94c199b271a027f41315d09d6a", "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "INVOICE", "EVENT", "CUSTOM" ] } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "properties": { "description": "Ajustes visuales agrupados. Claves admitidas: primary_color, secondary_color, border_color; cualquier otra devuelve 422. Los colores sueltos en la raíz se siguen aceptando por compatibilidad, pero properties es el formato vigente.", "properties": { "primary_color": { "description": "Encabezado, título, botón y saludo", "type": "string", "example": "#1A73E8", "nullable": true }, "secondary_color": { "description": "Pie personalizado", "type": "string", "example": "#5F6368", "nullable": true }, "border_color": { "description": "Borde del contenedor. Sin definir, se mantiene el del tema", "type": "string", "example": "#1A73E8", "nullable": true } }, "type": "object", "nullable": true }, "greeting_text": { "description": "HTML saneado. El límite cuenta el marcado, no solo el texto visible.", "type": "string", "maxLength": 2000, "example": "

Hola {{recipient_name}}

", "nullable": true }, "body_text": { "description": "HTML saneado", "type": "string", "maxLength": 10000, "example": "

Adjuntamos el documento {{document_number}} por {{document_total}}.

", "nullable": true }, "footer_text": { "description": "HTML saneado", "type": "string", "maxLength": 4000, "example": "

{{issuer_name}} — {{issuer_phone}}

", "nullable": true }, "subject_template": { "description": "Solo CUSTOM. Se guarda como texto plano aunque se envíe con marcado: es una cabecera de correo.", "type": "string", "example": "Documento {{document_number}}", "nullable": true }, "is_active": { "type": "boolean", "default": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Personalización guardada" }, "403": { "description": "Es una sub-cuenta: la personalización la define su casa de software" }, "422": { "description": "Tipo inválido, color mal formado o variables no permitidas" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/settings/email-branding/{type}/logo": { "post": { "tags": [ "Personalización de Correos" ], "summary": "Subir el logo de un tipo de correo", "description": "Sube el logo que se incrusta en el correo. Formatos admitidos: PNG, JPG y GIF, hasta 512 KB. Reemplaza el logo anterior si existía.", "operationId": "8c088f6915659682b75b49885bd19246", "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "INVOICE", "EVENT", "CUSTOM" ] } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "logo" ], "properties": { "logo": { "description": "Imagen PNG, JPG o GIF de hasta 512 KB", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Logo actualizado", "content": { "application/json": { "schema": { "properties": { "dataRecord": { "properties": { "logo_asset_id": { "type": "integer" }, "logo_url": { "type": "string" }, "email_type": { "type": "string" } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Es una sub-cuenta: la personalización la define su casa de software" }, "422": { "description": "Archivo ausente, formato no admitido o excede el tamaño" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Personalización de Correos" ], "summary": "Quitar el logo y volver al de la plataforma", "operationId": "5847f86f809635f0f03be5cef279bb6d", "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "INVOICE", "EVENT", "CUSTOM" ] } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Logo retirado" }, "403": { "description": "Es una sub-cuenta" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/settings/email-branding/{type}/preview": { "post": { "tags": [ "Personalización de Correos" ], "summary": "Previsualizar la personalización con datos de ejemplo", "description": "Renderiza los textos con datos de ejemplo, sin guardar nada. Si se envían textos en el cuerpo se previsualizan esos; si no, los ya configurados. Se aplica el mismo saneado de HTML que al guardar, así que la vista previa muestra exactamente lo que acabaría enviándose.", "operationId": "8889aba61b06400bb0c3fe0de8fcc401", "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "INVOICE", "EVENT", "CUSTOM" ] } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "greeting_text": { "description": "HTML saneado", "type": "string", "nullable": true }, "body_text": { "description": "HTML saneado", "type": "string", "nullable": true }, "footer_text": { "description": "HTML saneado", "type": "string", "nullable": true }, "subject_template": { "description": "Se devuelve como texto plano", "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Previsualización generada", "content": { "application/json": { "schema": { "properties": { "dataRecord": { "properties": { "email_type": { "type": "string" }, "sample_data": { "description": "Valores de ejemplo usados", "type": "object" }, "rendered": { "description": "Textos con las variables ya sustituidas", "type": "object" }, "branding": { "description": "Marca resuelta (logo y colores aplicables)", "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Tipo de correo inválido" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/ep/adjustment-note-type": { "get": { "tags": [ "Nómina Electrónica - Tablas" ], "summary": "Obtener tipos de nota de ajuste de nómina", "operationId": "f8c96c7258b788061a7d42c3af4b5749", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Tipos de nota de ajuste" } } } }, "/api/ubl2.1/ep/contract-type": { "get": { "tags": [ "Nómina Electrónica - Tablas" ], "summary": "Obtener tipos de contrato laboral", "operationId": "666fc57c8223a76a69775208fd230d5f", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Tipos de contrato" } } } }, "/api/ubl2.1/ep/disability-type": { "get": { "tags": [ "Nómina Electrónica - Tablas" ], "summary": "Obtener tipos de incapacidad", "operationId": "72150a2dcc57241b703674303aa52345", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Tipos de incapacidad" } } } }, "/api/ubl2.1/ep/extra-hours": { "get": { "tags": [ "Nómina Electrónica - Tablas" ], "summary": "Obtener tipos de horas extras", "operationId": "72880b621996ad2654906e7fdad82ee3", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Tipos de horas extras" } } } }, "/api/ubl2.1/ep/payroll-period": { "get": { "tags": [ "Nómina Electrónica - Tablas" ], "summary": "Obtener períodos de nómina", "operationId": "e9cc5736c963d8c748f22bdc7cdc101a", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Períodos de nómina" } } } }, "/api/ubl2.1/ep/worker-subtype": { "get": { "tags": [ "Nómina Electrónica - Tablas" ], "summary": "Obtener subtipos de trabajador", "operationId": "979d7395fb9a7380aaebea449b2f90a4", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Subtipos de trabajador" } } } }, "/api/ubl2.1/ep/worker-type": { "get": { "tags": [ "Nómina Electrónica - Tablas" ], "summary": "Obtener tipos de trabajador", "operationId": "fdace25f6df9c4c42a4eaf2fef61b546", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Tipos de trabajador" } } } }, "/api/ubl2.1/events/mailbox": { "get": { "tags": [ "Buzón de Recepción" ], "summary": "Listar los correos recibidos en el buzón", "description": "Lista los correos que llegaron al buzón de recepción de la empresa, incluidos los que NO generaron documento (IGNORED, FAILED) con el motivo en error_message: p. ej. adquiriente distinto («Documento descartado: el adquiriente (NIT …) no es esta empresa (NIT …)»), sin plan de pago vigente («El plan no incluye buzón de recepción»: FREE o nunca suscrita), virus, sin ZIP o sin cupo. can_retry indica si POST /events/mailbox/{id}/retry lo acepta. Los UNMATCHED no son visibles: no se resolvió empresa. Ordenados por fecha de recepción descendente.", "operationId": "6c96057f0d360b6823c0f8dc43793bdd", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID de una sub-cuenta propia (Casa de Software). Sin él se usa la empresa del token", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "Filtra por estado de procesamiento", "required": false, "schema": { "type": "string", "enum": [ "PENDING", "PROCESSED", "FAILED", "UNMATCHED", "IGNORED" ] } }, { "name": "query", "in": "query", "description": "Busca en asunto y remitente", "required": false, "schema": { "type": "string" } }, { "name": "startDate", "in": "query", "description": "Fecha inicial (Y-m-d)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "endDate", "in": "query", "description": "Fecha final (Y-m-d)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "archived", "in": "query", "description": "1 = muestra los archivados en vez de la bandeja principal", "required": false, "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "description": "Registros por página (máximo 50)", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 50 } } ], "responses": { "200": { "description": "Correos listados exitosamente", "content": { "application/json": { "schema": { "properties": { "dataRecords": { "properties": { "data": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "from_email": { "type": "string" }, "subject": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSED", "FAILED", "UNMATCHED", "IGNORED" ] }, "received_at": { "type": "string", "format": "date-time" }, "has_attachments": { "type": "boolean" }, "read_at": { "type": "string", "format": "date-time", "nullable": true }, "archived_at": { "type": "string", "format": "date-time", "nullable": true }, "starred": { "type": "boolean" }, "error_message": { "description": "Motivo por el que el correo no generó documento", "type": "string", "nullable": true }, "reason_code": { "description": "Motivo codificado: PLAN_EXPIRED = retenido por plan vencido; S3_OBJECT_MISSING = el correo ya no está en el almacenamiento.", "type": "string", "enum": [ "PLAN_EXPIRED", "S3_OBJECT_MISSING" ], "nullable": true }, "is_held": { "description": "Retenido por plan vencido (status IGNORED + reason_code PLAN_EXPIRED)", "type": "boolean" }, "can_retry": { "description": "true si POST /events/mailbox/{id}/retry lo acepta: FAILED o retenido, con ubicación guardada y dentro de la retención", "type": "boolean" }, "document_reception": { "description": "Documento generado, o null si el correo no produjo ninguno", "properties": { "id": { "type": "integer" }, "folio": { "type": "string" }, "total": { "type": "number" }, "issue_date": { "type": "string", "format": "date" } }, "type": "object", "nullable": true } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "403": { "$ref": "#/components/responses/ReceptionNotInPlan" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/events/mailbox/{id}": { "get": { "tags": [ "Buzón de Recepción" ], "summary": "Ver el detalle de un correo del buzón", "description": "Devuelve el correo con su vista previa, el documento asociado si lo hubo y los archivos custodiados. La descarga de cada archivo se hace por el endpoint de document-receptions.", "operationId": "6e03bdfd155cf6455303a307de2e2e58", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "client_uuid", "in": "query", "description": "UUID de una sub-cuenta propia (Casa de Software). Sin él se usa la empresa del token", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Correo encontrado", "content": { "application/json": { "schema": { "properties": { "dataRecord": { "properties": { "id": { "type": "integer" }, "from_email": { "type": "string" }, "to_email": { "type": "string" }, "subject": { "type": "string", "nullable": true }, "message_id": { "type": "string" }, "status": { "type": "string" }, "received_at": { "type": "string", "format": "date-time" }, "processed_at": { "type": "string", "format": "date-time", "nullable": true }, "body_preview": { "type": "string", "nullable": true }, "error_message": { "type": "string", "nullable": true }, "reason_code": { "type": "string", "enum": [ "PLAN_EXPIRED", "S3_OBJECT_MISSING" ], "nullable": true }, "is_held": { "type": "boolean" }, "can_retry": { "type": "boolean" }, "files": { "description": "Archivos custodiados; vacío si el correo no generó documento", "type": "array", "items": { "properties": { "id": { "type": "integer" }, "type_document": { "type": "string", "enum": [ "INBOUND_EMAIL_RAW", "XML", "ZIP" ] }, "file_name": { "type": "string" }, "mime_type": { "type": "string" }, "file_size": { "type": "integer", "nullable": true } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "403": { "$ref": "#/components/responses/ReceptionNotInPlan" }, "404": { "description": "Correo no encontrado en el buzón" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/events/mailbox/address": { "get": { "tags": [ "Buzón de Recepción" ], "summary": "Obtener la dirección completa del buzón de recepción", "description": "Devuelve la dirección a la que los proveedores deben enviar las facturas: {email_reception}@{dominio}. El identificador es de la EMPRESA (uno solo, en la persona de recepción por defecto) y la dirección no cambia al cambiar la persona por defecto; si la empresa eliminó su última persona, la dirección se conserva y reception_person_uuid es null. Solo lectura: si la empresa aún no tiene buzón, responde 200 con address=null y provisioned=false.", "operationId": "e4e621b6c237657e025a7f5fb35b5847", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID de una sub-cuenta propia (Casa de Software). Sin él se usa la empresa del token", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Dirección del buzón (o null si aún no está asignada)", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "dataRecord": { "properties": { "address": { "description": "Dirección completa; null si no está asignada", "type": "string", "format": "email", "example": "k7m2p9x4vq@buzon.ejemplo.com", "nullable": true }, "local_part": { "type": "string", "example": "k7m2p9x4vq", "nullable": true }, "domain": { "type": "string", "example": "buzon.ejemplo.com", "nullable": true }, "provisioned": { "description": "false si la empresa aún no tiene persona de recepción con identificador", "type": "boolean", "example": true }, "reception_person_uuid": { "description": "Persona de recepción por defecto que guarda la dirección; null si la empresa eliminó su última persona", "type": "string", "format": "uuid", "nullable": true }, "message": { "description": "Explicación cuando provisioned=false; null en otro caso", "type": "string", "nullable": true } }, "type": "object" } }, "type": "object" } } } }, "403": { "$ref": "#/components/responses/ReceptionNotInPlan" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/events/mailbox/{id}/retry": { "post": { "tags": [ "Buzón de Recepción" ], "summary": "Reintentar el procesamiento de un correo del buzón", "description": "Los IGNORED por virus, otro NIT, sin XML o topes no se reintentan (422). Idempotente: si ya está en proceso responde 409 MAILBOX_RETRY_IN_PROGRESS y no encola otro. El reproceso revalida todo (plan, cupo, NIT): el resultado se ve en la bandeja.", "operationId": "93132ff762df12c6c6f2cc2d9d95d74e", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "client_uuid", "in": "query", "description": "UUID de una sub-cuenta propia (Casa de Software). Sin él se usa la empresa del token", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Correo reencolado", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "El correo se volvió a poner en cola para procesarlo." }, "dataRecord": { "properties": { "id": { "type": "integer", "example": 1532 }, "status": { "type": "string", "enum": [ "PENDING" ], "example": "PENDING" } }, "type": "object" } }, "type": "object" } } } }, "403": { "$ref": "#/components/responses/ReceptionNotInPlan" }, "404": { "description": "Correo no encontrado en el buzón de la empresa" }, "409": { "description": "No se puede reintentar", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailboxRetryError" } } } }, "422": { "description": "El correo no es reintentable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailboxRetryError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/events/mailbox/quota": { "get": { "tags": [ "Buzón de Recepción" ], "summary": "Consumo del cupo de recepción", "description": "Cuántos documentos recibidos lleva la empresa frente al límite de su plan: el mismo cálculo que decide si un correo nuevo se procesa (sin cupo, el correo queda FAILED «Sin cupo disponible»). El cupo es el de la suscripción vigente (la de la Casa de Software si la empresa es sub-cuenta) y su contador de recepción, aparte del de emisión. level: OK, WARNING (> 80 %), CRITICAL (> 95 %), EXHAUSTED (usados >= límite) o UNLIMITED. Con shared_pool=true y consultado por la propia sub-cuenta (con o sin su client_uuid) used, limit y remaining vienen en null: solo se muestra el porcentaje de la bolsa de la Casa de Software.", "operationId": "7975da11197444be42085e7cbc03c002", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID de una sub-cuenta propia (Casa de Software). Sin él se usa la empresa del token", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Consumo del cupo", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "dataRecord": { "properties": { "unlimited": { "type": "boolean", "example": false }, "used": { "type": "integer", "example": 850, "nullable": true }, "limit": { "description": "null si es ilimitado o si se ocultan las cifras de la bolsa", "type": "integer", "example": 1000, "nullable": true }, "remaining": { "type": "integer", "example": 150, "nullable": true }, "percent": { "description": "used * 100 / limit, 2 decimales, sin acotar; 100 con límite 0; null si es ilimitado", "type": "number", "format": "float", "example": 85, "nullable": true }, "exhausted": { "type": "boolean", "example": false }, "level": { "type": "string", "enum": [ "OK", "WARNING", "CRITICAL", "EXHAUSTED", "UNLIMITED" ], "example": "WARNING" }, "shared_pool": { "description": "true: la empresa es sub-cuenta y consume la bolsa de su Casa de Software", "type": "boolean" }, "period_start": { "type": "string", "format": "date", "nullable": true }, "period_end": { "type": "string", "format": "date", "nullable": true }, "message": { "type": "string", "example": "Ya usaste más del 80 % de tu cupo de recepción.", "nullable": true }, "upgrade_route": { "type": "string", "example": "/membership/subscription" } }, "type": "object" } }, "type": "object" } } } }, "403": { "$ref": "#/components/responses/ReceptionNotInPlan" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/events/reception-people": { "get": { "tags": [ "Personas de Recepción" ], "summary": "Listar las personas de recepción y el modo de la empresa", "operationId": "b62046956b16f600c8b473af4e4a372c", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID de una sub-cuenta propia (Casa de Software). Sin él se usa la empresa del token", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Personas de la empresa (vacío si no tiene)", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "dataRecord": { "$ref": "#/components/schemas/ReceptionPeopleState" } }, "type": "object" } } } }, "403": { "$ref": "#/components/responses/ReceptionNotInPlan" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Personas de Recepción" ], "summary": "Registrar una persona de recepción", "description": "La primera persona de la empresa nace por defecto y recibe el buzón: el identificador existente si la empresa ya tuvo uno (eliminó su última persona) o uno nuevo. Las siguientes no generan identificador y heredan el modo de la empresa. Una empresa nueva arranca en modo manual (send_events=false).", "operationId": "2ae217e70b48632ee75c2e4cb32d4daa", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceptionPersonInput" } } } }, "responses": { "201": { "description": "Persona registrada", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Persona de recepción registrada." }, "dataRecord": { "$ref": "#/components/schemas/ReceptionPerson" } }, "type": "object" } } } }, "403": { "$ref": "#/components/responses/ReceptionNotInPlan" }, "422": { "description": "Datos inválidos, o se enviaron is_default, send_events, email_reception o company_id" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/events/reception-people/{uuid}": { "put": { "tags": [ "Personas de Recepción" ], "summary": "Editar los datos de una persona de recepción", "description": "Edición parcial. No cambia la persona por defecto, el buzón ni el modo. Los eventos ya emitidos no cambian: su firma quedó en el XML.", "operationId": "967391fe3eb9431837f34a81df6f1f75", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceptionPersonInput" } } } }, "responses": { "200": { "description": "Persona actualizada", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Persona de recepción actualizada." }, "dataRecord": { "$ref": "#/components/schemas/ReceptionPerson" } }, "type": "object" } } } }, "403": { "$ref": "#/components/responses/ReceptionNotInPlan" }, "404": { "description": "La persona no existe, fue eliminada o es de otra empresa (misma respuesta)" }, "422": { "description": "Datos inválidos, o se enviaron is_default, send_events, email_reception o company_id" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Personas de Recepción" ], "summary": "Eliminar una persona de recepción", "description": "No se puede eliminar la persona por defecto si hay otras: primero marque otra (409). La última sí se puede eliminar: la dirección del buzón se conserva (sigue recibiendo correo, en modo manual) y pasa a la próxima persona que se registre.", "operationId": "9b7486b4efcf066689c89023c805ee2a", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "client_uuid", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Persona eliminada; devuelve el estado resultante", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Persona de recepción eliminada." }, "dataRecord": { "$ref": "#/components/schemas/ReceptionPeopleState" } }, "type": "object" } } } }, "403": { "$ref": "#/components/responses/ReceptionNotInPlan" }, "404": { "description": "La persona no existe, fue eliminada o es de otra empresa (misma respuesta)" }, "409": { "description": "Es la persona por defecto y hay otras registradas", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No se puede eliminar la persona de recepción por defecto mientras haya otras registradas. Marque otra como persona por defecto y vuelva a intentarlo." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/events/reception-people/{uuid}/default": { "post": { "tags": [ "Personas de Recepción" ], "summary": "Marcar la persona de recepción por defecto", "description": "La persona por defecto firma los eventos automáticos del buzón y es la que se usa cuando no se indica reception_person_uuid. El buzón (misma dirección) y el modo automático/manual se trasladan de la anterior: no cambian. Idempotente.", "operationId": "8a42eeb1fdfbe634ec32d6b73f4eba78", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "client_uuid", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Persona marcada; devuelve el estado resultante", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Persona de recepción por defecto actualizada." }, "dataRecord": { "$ref": "#/components/schemas/ReceptionPeopleState" } }, "type": "object" } } } }, "403": { "$ref": "#/components/responses/ReceptionNotInPlan" }, "404": { "description": "La persona no existe, fue eliminada o es de otra empresa (misma respuesta)" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/events/reception-people/mode": { "put": { "tags": [ "Personas de Recepción" ], "summary": "Cambiar el modo de eventos de la empresa (automático o manual)", "description": "Configuración de la EMPRESA, no de una persona. true: 030, 032 y 033 automáticos (el 033 automático quita la posibilidad de reclamar con el 031). false: buzón sin eventos automáticos; Excel/CUFE solo el 030.", "operationId": "2fa1f2a1213ade1b5e4d07198478f251", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "send_events" ], "properties": { "send_events": { "type": "boolean", "example": false }, "client_uuid": { "type": "string", "format": "uuid", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Modo actualizado; devuelve el estado resultante", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Modo de eventos actualizado." }, "dataRecord": { "$ref": "#/components/schemas/ReceptionPeopleState" } }, "type": "object" } } } }, "403": { "$ref": "#/components/responses/ReceptionNotInPlan" }, "409": { "description": "La empresa no tiene personas de recepción" }, "422": { "description": "send_events ausente o no booleano" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/countries": { "get": { "tags": [ "Ubicación" ], "summary": "Obtener lista de países", "operationId": "c086a9b136ded2812226e9e950b7da7e", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Lista de países obtenida exitosamente" } } } }, "/api/ubl2.1/departments": { "get": { "tags": [ "Ubicación" ], "summary": "Obtener lista de departamentos de Colombia", "operationId": "059b847b3791f91833ea6ad0d2e3ffa0", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Lista de departamentos obtenida exitosamente" } } } }, "/api/ubl2.1/cities": { "get": { "tags": [ "Ubicación" ], "summary": "Obtener lista de ciudades", "operationId": "bbffc56e4e936b089e59230f594d4746", "parameters": [ { "name": "department_id", "in": "query", "description": "ID del departamento", "schema": { "type": "integer" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Lista de ciudades obtenida exitosamente" } } } }, "/api/ubl2.1/email-logs/{id}": { "get": { "tags": [ "Registros de Email" ], "summary": "Obtener registro de email específico", "operationId": "aa1beaf8cb879dd7542c82a0e332d51f", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Registro de email obtenido exitosamente" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/email-logs": { "get": { "tags": [ "Registros de Email" ], "summary": "Listar todos los registros de email", "operationId": "0fb7f55f026edafaac9e26772eb2857f", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Registros de email obtenidos exitosamente", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/email-logs/document/{document_id}": { "get": { "tags": [ "Registros de Email" ], "summary": "Buscar registros de email por ID de documento", "operationId": "940614bebd98c91ccab8966976f34ccd", "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Registros de email obtenidos exitosamente", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/claim-concepts": { "get": { "tags": [ "Tablas Maestras" ], "summary": "Obtener conceptos de reclamación", "operationId": "80b919e1fbf7c2a8b69004882584ce50", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Conceptos de reclamación" } } } }, "/api/ubl2.1/delivery-conditions": { "get": { "tags": [ "Tablas Maestras" ], "summary": "Obtener condiciones de entrega", "operationId": "93ac6d8867f032e7631950ddcaf49023", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Lista de condiciones de entrega" } } } }, "/api/ubl2.1/health/user-type": { "get": { "tags": [ "Tablas Maestras" ], "summary": "Obtener tipos de usuario del sector salud", "operationId": "3f4c93f8cd5726c3ec2e22a85233f382", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Tipos de usuario salud" } } } }, "/api/ubl2.1/health/contracting": { "get": { "tags": [ "Tablas Maestras" ], "summary": "Obtener modalidades de contratación salud", "operationId": "fc93335dd7931b8870c9f3158f2fa0eb", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Modalidades de contratación" } } } }, "/api/ubl2.1/health/coverage": { "get": { "tags": [ "Tablas Maestras" ], "summary": "Obtener coberturas del sector salud", "operationId": "7c5efc2a9ccbf68e1f2f58e1d8d756ef", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Coberturas salud" } } } }, "/api/ubl2.1/health/invoice-without-contract-justifications": { "get": { "tags": [ "Tablas Maestras" ], "summary": "Obtener justificaciones de facturación sin contrato", "operationId": "a86f66d954305083b37fb2010964bc39", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Justificaciones de facturación sin contrato" } } } }, "/api/ubl2.1/health/operation-types": { "get": { "tags": [ "Tablas Maestras" ], "summary": "Obtener tipos de operación del sector salud", "operationId": "f9b05a0c24722ec0655e30829b433cbd", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Tipos de operación salud" } } } }, "/api/ubl2.1/discount-codes": { "get": { "tags": [ "Tablas Maestras" ], "summary": "Obtener códigos de descuento", "operationId": "29916cf0303fe05b560d6e0a438fe4a2", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Códigos de descuento" } } } }, "/api/ubl2.1/payment-means": { "get": { "tags": [ "Tablas Maestras" ], "summary": "Obtener medios de pago", "operationId": "c92ad650e370d009762f60e76ed044b0", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Medios de pago" } } } }, "/api/ubl2.1/payment-methods": { "get": { "tags": [ "Tablas Maestras" ], "summary": "Obtener formas de pago", "operationId": "e94bdcbb829497b72a8641c1d6cc48e1", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Formas de pago" } } } }, "/api/ubl2.1/reference-price": { "get": { "tags": [ "Tablas Maestras" ], "summary": "Obtener precios de referencia", "operationId": "5d26731eba37a30a08a71acc7a966135", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Precios de referencia" } } } }, "/api/ubl2.1/type-item-identifications": { "get": { "tags": [ "Tablas Maestras" ], "summary": "Obtener tipos de identificación de ítems", "operationId": "7b97b5d379ca8370a8cbad75a95ac38c", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Tipos de identificación de ítems" } } } }, "/api/ubl2.1/quantity-units": { "get": { "tags": [ "Tablas Maestras" ], "summary": "Obtener unidades de medida", "operationId": "8237cc07a8dcdf8ac16b08688cd27dc1", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Unidades de medida" } } } }, "/api/ubl2.1/organization-type": { "get": { "tags": [ "Tablas Maestras" ], "summary": "Obtener tipos de organización", "operationId": "96ede71f130be6b61b334472e8a0e489", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Tipos de organización" } } } }, "/api/ubl2.1/identity-documents": { "get": { "tags": [ "Tablas Maestras" ], "summary": "Obtener tipos de documento de identidad", "operationId": "e327b62510825056d32fb6327ced8562", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Tipos de documento" } } } }, "/api/ubl2.1/operation-type": { "get": { "tags": [ "Tablas Maestras" ], "summary": "Obtener tipos de operación", "operationId": "0c1be75b650a75a6d887a59df13aecb4", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Tipos de operación" } } } }, "/api/ubl2.1/document-type": { "get": { "tags": [ "Tablas Maestras" ], "summary": "Obtener tipos de documento", "operationId": "39c2ebb546b1cd3578fb149705d279e3", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Tipos de documento" } } } }, "/api/ubl2.1/destination-environment": { "get": { "tags": [ "Tablas Maestras" ], "summary": "Obtener ambientes de destino (producción/pruebas)", "operationId": "8b4cd4ab20aedd525179d476442ecd24", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Ambientes de destino" } } } }, "/api/ubl2.1/correction-notes": { "get": { "tags": [ "Tablas Maestras" ], "summary": "Obtener conceptos de notas de corrección", "operationId": "29c0c51d96e4f3d7dbecab649819f079", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Conceptos de notas" } } } }, "/api/ubl2.1/currencies": { "get": { "tags": [ "Tablas Maestras" ], "summary": "Obtener monedas", "operationId": "81e069d38a2fb977b598dfab79574753", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Lista de monedas" } } } }, "/api/ubl2.1/memberships/quotas": { "post": { "tags": [ "Membresías" ], "summary": "Asignar cuota de documentos a un cliente", "description": "La Casa de Software (siempre la empresa del token) asigna o reemplaza (upsert) la cuota de documentos de uno de sus clientes, identificado por `client_uuid` (en el cuerpo o en la query). Solo usuarios ADMINISTRADOR (type_id=1) o DESARROLLADOR (type_id=2). Valida que la Casa de Software no tenga plan FREE y que tenga documentos disponibles. `client_company_id` (id interno) se acepta temporalmente como alias obsoleto cuando no se envía `client_uuid`.", "operationId": "c16828fed012af2bfde59514d0e8d56b", "parameters": [ { "name": "client_uuid", "in": "query", "required": false, "description": "UUID del cliente (sub-cuenta) que recibe la cuota. Alternativa a enviarlo en el body. La Casa de Software que asigna es siempre la empresa del token.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "client_uuid", "assigned_documents", "start_date", "end_date" ], "properties": { "client_uuid": { "description": "UUID del cliente (sub-cuenta) de la Casa de Software. También se acepta en la query.", "type": "string", "format": "uuid", "example": "1f3a0b11-b698-11f1-a6c7-d843ae899220" }, "client_company_id": { "description": "Obsoleto: id interno del cliente. Solo se usa si no se envía client_uuid. Use client_uuid.", "type": "integer", "example": 123, "deprecated": true }, "assigned_documents": { "description": "Número de documentos a asignar al cliente", "type": "integer", "example": 1000 }, "start_date": { "description": "Fecha de inicio de vigencia de la cuota", "type": "string", "format": "date", "example": "2026-01-01" }, "end_date": { "description": "Fecha de finalización de vigencia de la cuota", "type": "string", "format": "date", "example": "2026-12-31" } }, "type": "object" } } } }, "responses": { "201": { "description": "Cuota asignada correctamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Cuota asignada correctamente." }, "quota": { "properties": { "id": { "type": "integer", "example": 1 }, "subscription_id": { "type": "integer", "example": 5 }, "client_company_id": { "type": "integer", "example": 123 }, "client_uuid": { "type": "string", "format": "uuid", "example": "1f3a0b11-b698-11f1-a6c7-d843ae899220" }, "assigned_documents": { "type": "integer", "example": 1000 }, "consumed_documents": { "type": "integer", "example": 0 }, "start_date": { "type": "string", "format": "date", "example": "2026-01-01" }, "end_date": { "type": "string", "format": "date", "example": "2026-12-31" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "El usuario no es ADMINISTRADOR ni DESARROLLADOR", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No tienes permisos para asignar cuotas a clientes." } }, "type": "object" } } } }, "402": { "description": "Plan FREE o sin suscripción activa", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "El plan FREE no permite asignar cuotas a clientes. Actualice su plan para acceder a esta funcionalidad." } }, "type": "object" } } } }, "404": { "description": "El cliente no existe o no es cliente de la Casa de Software", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "El cliente no existe." } }, "type": "object" } } } }, "409": { "description": "No hay suficientes documentos disponibles para asignar", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No tiene suficientes documentos disponibles para asignar. Disponibles: 500, Solicitados: 1000" }, "available_documents": { "description": "Documentos disponibles para asignar", "type": "integer", "example": 500 }, "requested_documents": { "description": "Documentos solicitados", "type": "integer", "example": 1000 }, "total_documents": { "description": "Total de documentos del plan", "type": "integer", "example": 5000 }, "consumed_documents": { "description": "Documentos ya consumidos", "type": "integer", "example": 2000 }, "already_assigned": { "description": "Documentos ya asignados a otros clientes", "type": "integer", "example": 2500 } }, "type": "object" } } } }, "422": { "description": "Error de validación en los datos enviados (p. ej. falta client_uuid)", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "El UUID del cliente (client_uuid) es obligatorio." }, "errors": { "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/memberships/quotas/{client}": { "delete": { "tags": [ "Membresías" ], "summary": "Eliminar cuota asignada a un cliente", "description": "La Casa de Software (siempre la empresa del token) elimina la cuota de uno de sus clientes. Solo usuarios ADMINISTRADOR (type_id=1) o DESARROLLADOR (type_id=2). Después de eliminar la cuota, el cliente volverá a consumir de la bolsa general según el Modo Híbrido.", "operationId": "d84b70dda638e8f20e24a9b57ccd3c84", "parameters": [ { "name": "client", "in": "path", "description": "client_uuid del cliente. Obsoleto: un valor numérico se toma como el id interno (client_company_id).", "required": true, "schema": { "type": "string", "example": "1f3a0b11-b698-11f1-a6c7-d843ae899220" } } ], "responses": { "200": { "description": "Cuota eliminada correctamente (o el cliente no tenía cuota)", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Cuota eliminada correctamente. El cliente ahora consume de la bolsa general." }, "data": { "properties": { "client_uuid": { "type": "string", "format": "uuid", "example": "1f3a0b11-b698-11f1-a6c7-d843ae899220" }, "client_company_id": { "type": "integer", "example": 123 }, "consumption_mode": { "description": "Modo de consumo: shared_pool (bolsa compartida) o unlimited (ilimitado heredado)", "type": "string", "example": "shared_pool" } }, "type": "object" } }, "type": "object" } } } }, "402": { "description": "El usuario no es ADMINISTRADOR ni DESARROLLADOR, o la Casa de Software no tiene suscripción activa", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No tienes permisos para eliminar cuotas de clientes." } }, "type": "object" } } } }, "404": { "description": "El cliente no existe o no es cliente de la Casa de Software", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "El cliente no existe." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/memberships/summary": { "get": { "tags": [ "Membresías" ], "summary": "Obtener resumen de membresía y consumo", "operationId": "20651dd351b2806054aceb443a67e205", "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Filtra assigned_quotas por razón social del cliente (coincidencia parcial). Solo en type developer.", "schema": { "type": "string", "example": "COMERCIAL" } }, { "name": "page", "in": "query", "required": false, "description": "Página de assigned_quotas (15 por página)", "schema": { "type": "integer", "minimum": 1, "example": 1 } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Resumen de membresía", "content": { "application/json": { "schema": { "properties": { "data": { "type": "object", "required": [ "type", "plan_name", "is_unlimited" ], "properties": { "type": { "type": "string", "enum": [ "developer", "client_quota", "client_shared" ], "example": "developer" }, "plan_name": { "type": "string", "description": "Nombre del plan. En sub-cuentas: «Cuota de » o «Plan (Compartido)»", "example": "PREMIUM" }, "is_unlimited": { "type": "boolean", "description": "false cuando no aplica (client_quota)", "example": false }, "valid_until": { "type": "string", "format": "date", "example": "2026-12-31", "description": "YYYY-MM-DD" }, "limit": { "type": "integer", "description": "Documentos de la bolsa (suma de las suscripciones activas) o de la cuota", "example": 5000 }, "consumed": { "type": "integer", "description": "Documentos consumidos. En client_shared, el consumo total de la Casa de Software", "example": 2500 }, "assigned_quotas": { "type": "object", "description": "Solo en type developer. Cuotas asignadas a sub-cuentas, paginadas de 15 en 15 (current_page, data, per_page, total, last_page y enlaces de paginación)", "properties": { "current_page": { "type": "integer", "example": 1 }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "uuid": { "type": "string", "format": "uuid", "example": "6f1c2b9e-3d4a-4e8b-9a71-2c5d8e0f4b13" }, "subscription_id": { "type": "integer", "example": 5 }, "client_company_id": { "type": "integer", "example": 123 }, "assigned_documents": { "type": "integer", "example": 1000 }, "consumed_documents": { "type": "integer", "example": 120 }, "start_date": { "type": "string", "format": "date-time", "example": "2026-01-01T05:00:00.000000Z", "description": "Medianoche de Bogotá de la fecha enviada, en UTC (ISO 8601)" }, "end_date": { "type": "string", "format": "date-time", "example": "2026-12-31T05:00:00.000000Z", "description": "Medianoche de Bogotá de la fecha enviada, en UTC (ISO 8601)" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-10-14T15:20:11.000000Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-10-14T15:20:11.000000Z" }, "client": { "type": "object", "properties": { "id": { "type": "integer", "example": 123 }, "company_name": { "type": "string", "example": "COMERCIAL EJEMPLO SAS" } } } } } }, "per_page": { "type": "integer", "example": 15 }, "total": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 } } }, "daily_limit": { "type": "object", "description": "Solo en type developer con plan FREE", "properties": { "limit": { "type": "integer", "example": 10 }, "consumed": { "type": "integer", "example": 3 }, "remaining": { "type": "integer", "example": 7 }, "next_reset": { "type": "string", "format": "date-time", "example": "2026-10-22T00:00:00-05:00", "description": "ISO 8601" } } } } } }, "type": "object" } } } }, "401": { "description": "No autenticado" }, "404": { "description": "La cuenta no tiene membresía activa (o la Casa de Software de la sub-cuenta no la tiene)", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "No se encontró una membresía activa o legada para esta cuenta." }, "data": { "type": "object", "nullable": true }, "success": { "type": "boolean", "example": false } } } } } } }, "security": [ { "bearerAuth": [] } ], "description": "Resumen del plan y del consumo de la empresa (o de la sub-cuenta indicada con client_uuid). type indica el caso: developer (cuenta principal o Casa de Software), client_quota (sub-cuenta con cuota propia) o client_shared (sub-cuenta que consume de la bolsa de su Casa de Software). La respuesta va envuelta en data, sin success." } }, "/api/ubl2.1/memberships/recharges": { "get": { "tags": [ "Membresías" ], "summary": "Recargas de documentos de la suscripción activa", "description": "Desglose del límite de documentos de la suscripción activa (lo que viene del plan y lo que viene de recargas), los documentos recargados sin usar, su vencimiento y la lista de recargas: las del ciclo vigente (ACTIVE) y, debajo, las de planes anteriores de la misma empresa que se trasladaron en un cambio de plan (TRANSFERRED). Solo lectura y sin datos del pago (ni precio, ni monto, ni referencia). Las recargas no tienen vencimiento propio: vencen con la suscripción (end_date). Se consumen primero los documentos del plan. En la renovación, el upgrade y el downgrade, los recargados sin usar se trasladan como documentos a la suscripción nueva y sus recargas pasan a TRANSFERRED: siguen listándose como historial (últimos 12 meses, máximo 50), pero no suman en recharged_documents ni en unused_recharged_documents, que son solo del ciclo vigente. Admite client_uuid para consultar una sub-cuenta propia, como el resto de endpoints de membresía.", "operationId": "49ddf047bd2d859ad208366b76341bc6", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID de una sub-cuenta (cliente) del desarrollador autenticado. Sin él, la empresa del token", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Recargas de la suscripción activa. Sin recargas (o con un plan ilimitado): recharges vacío y recharged_documents y unused_recharged_documents en 0", "content": { "application/json": { "schema": { "properties": { "plan_documents": { "description": "Tamaño del plan del catálogo; si el catálogo no lo tiene, base_documents", "type": "integer", "example": 8000 }, "base_documents": { "description": "Documentos del límite que no vienen de recargas del ciclo vigente: la bolsa del plan más lo que la suscripción traía al crearse (documentos trasladados de un plan anterior o un ajuste). base_documents + recharged_documents = total_documents", "type": "integer", "example": 8000 }, "recharged_documents": { "description": "Documentos recargados en el ciclo vigente", "type": "integer", "example": 300 }, "total_documents": { "description": "Límite de documentos de la suscripción activa", "type": "integer", "example": 8300 }, "unused_recharged_documents": { "description": "Documentos recargados sin usar: se consumen primero los del plan, así que es min(recharged_documents, total_documents - consumidos)", "type": "integer", "example": 300 }, "end_date": { "description": "Vencimiento de la suscripción y de sus recargas (Y-m-d)", "type": "string", "format": "date", "example": "2027-01-30" }, "remaining_days": { "description": "Días calendario hasta el vencimiento; el día en curso cuenta como no usado", "type": "integer", "example": 105 }, "expiry_warning": { "description": "true si remaining_days < 30 y quedan documentos recargados sin usar", "type": "boolean", "example": false }, "expiry_message": { "description": "Texto del aviso cuando expiry_warning es true, p. ej. 'Tu plan vence en 12 días (2026-10-29). Los documentos recargados que no uses antes de esa fecha se pierden.'; null en otro caso", "type": "string", "example": null, "nullable": true }, "transferred_count": { "description": "Cantidad de recargas TRANSFERRED incluidas en recharges", "type": "integer", "example": 1 }, "recharges": { "description": "Primero las ACTIVE (ciclo vigente) y después las TRANSFERRED (planes anteriores de la misma empresa, cerradas en los últimos 12 meses, máximo 50); en cada grupo, la más reciente primero", "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 12 }, "date": { "description": "Fecha y hora de la recarga (Y-m-d H:i:s)", "type": "string", "example": "2026-10-17 09:42:10" }, "documents": { "description": "Documentos que se recargaron (no los trasladados)", "type": "integer", "example": 300 }, "status": { "description": "ACTIVE: del ciclo vigente, suma al límite y vence con la suscripción. TRANSFERRED: de un plan anterior; los documentos que no se usaron pasaron al plan actual en el cambio de plan y ya están en base_documents", "type": "string", "enum": [ "ACTIVE", "TRANSFERRED" ], "example": "ACTIVE" }, "transferred_at": { "description": "Solo TRANSFERRED: fecha del traslado (Y-m-d); null en ACTIVE", "type": "string", "format": "date", "example": null, "nullable": true }, "from_plan_name": { "description": "Solo TRANSFERRED: nombre del plan de origen, p. ej. 'PLAN BÁSICO'; null en ACTIVE", "type": "string", "example": null, "nullable": true } }, "type": "object" } }, "success": { "type": "boolean", "example": true } }, "type": "object" } } } }, "401": { "description": "No autenticado" }, "403": { "description": "Usuario sin empresa, empresa inactiva o client_uuid de una empresa que no es sub-cuenta activa de quien llama" }, "404": { "description": "No tienes una suscripción activa, o la empresa no existe" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/settings/reports": { "get": { "tags": [ "Configuración de Reportes" ], "summary": "Obtener configuración de reportes", "operationId": "0d920ff6a87760203db851005bed8c79", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Configuración obtenida exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/settings/reports/{id}": { "put": { "tags": [ "Configuración de Reportes" ], "summary": "Actualizar configuración de reportes", "operationId": "553993b34686cd18bbef5547ca563cee", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "header_text": { "type": "string" }, "footer_text": { "type": "string" }, "logo_url": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Configuración actualizada exitosamente" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Configuración de Reportes" ], "summary": "Eliminar configuración de reportes", "operationId": "eed59e0866853f718ac2bf561c70b327", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Configuración eliminada exitosamente" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/settings/reports/{id}/image": { "put": { "tags": [ "Configuración de Reportes" ], "summary": "Actualizar imagen de encabezado de reportes", "operationId": "fa116eeaa1827b775399fde871711b2f", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "imgdata": { "description": "Imagen en base64", "type": "string" }, "imgname": { "description": "Nombre del archivo de imagen", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Imagen actualizada exitosamente" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/resolutions": { "get": { "tags": [ "Resoluciones DIAN" ], "summary": "Listar resoluciones DIAN", "operationId": "77679c1c577404e3fd40bf35fa80d33a", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Lista de resoluciones obtenida exitosamente", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Resoluciones DIAN" ], "summary": "Crear resolución DIAN", "operationId": "75cbf022793050cab33a6dcc9dda17de", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "records" ], "properties": { "records": { "description": "JSON serializado con los datos de la resolución. Si falta o no es JSON: 422 «El campo records es requerido» / «El campo records debe ser un JSON válido».", "type": "string", "format": "json", "example": "{\"type_document_id\":7,\"resolution_number\":\"18760000001\",\"prefix\":\"SETP\",\"invoice_name\":\"FACTURA ELECTRÓNICA DE VENTA\",\"range_from\":990000000,\"range_up\":995000000,\"date_from\":\"2026-01-01\",\"date_up\":\"2027-12-31\",\"initial_number\":990000000,\"active\":1,\"technical_key\":\"fc8eac422eba16e22ffd8c6f94b3f40a6e38162c\",\"headerline1\":\"\",\"headerline2\":\"\",\"footline1\":\"\",\"footline2\":\"\",\"footline3\":\"\",\"footline4\":\"\"}" } }, "type": "object" } } } }, "responses": { "200": { "description": "Resolución creada (HTTP 200, no 201). record es la fila creada, con su id", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Registro creado correctamente." }, "record": { "type": "object", "example": { "id": 15, "company_id": 3, "type_document_id": 7, "resolution_number": "18760000001", "prefix": "SETP", "invoice_name": "FACTURA ELECTRÓNICA DE VENTA", "range_from": 990000000, "range_up": 995000000, "date_from": "2026-01-01", "date_up": "2027-12-31", "initial_number": 990000000, "active": 1, "technical_key": "fc8eac422eba16e22ffd8c6f94b3f40a6e38162c", "headerline1": "", "headerline2": "", "footline1": "", "footline2": "", "footline3": "", "footline4": "" } }, "success": { "type": "boolean", "example": true } } } } } }, "400": { "description": "Ya existe una resolución con el mismo tipo de documento, número y prefijo", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Ya existe una resolución con el mismo número(18760000001) y\n prefijo(SETP). Por favor verifique" }, "success": { "type": "boolean", "example": false } }, "type": "object" } } } }, "422": { "description": "Fallo de validación. Con varios errores, message añade « (and N more errors)»", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Validación fallida" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "success": { "type": "boolean", "description": "Solo en la validación de los campos de records", "example": false } }, "type": "object" }, "examples": { "records_invalido": { "summary": "records ausente o no es JSON", "value": { "message": "El campo records es requerido", "errors": { "records": [ "El campo records es requerido" ] } } }, "campos": { "summary": "Campos de records", "value": { "message": "Validación fallida", "errors": { "resolution_number": [ "El campo resolution_number es requerido" ] }, "success": false } } } } } } }, "security": [ { "bearerAuth": [] } ], "description": "Crea una resolución de numeración. records es un JSON serializado (string). Obligatorios dentro de records: type_document_id, invoice_name (máx. 120), range_from, range_up, date_from, date_up, resolution_number (máx. 20), initial_number y active. prefix es opcional (máx. 20; vacío si se omite). No se admiten dos resoluciones con la misma empresa, tipo de documento, número y prefijo." } }, "/api/ubl2.1/resolutions/{id}": { "get": { "tags": [ "Resoluciones DIAN" ], "summary": "Obtener una resolución DIAN por ID", "operationId": "1aaf38609405944bbf7f96981ea9d14d", "parameters": [ { "name": "id", "in": "path", "description": "ID de la resolución a consultar", "required": true, "schema": { "type": "integer", "example": 1 } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Resolución obtenida exitosamente", "content": { "application/json": { "schema": { "properties": { "dataRecords": { "properties": { "data": { "type": "array", "items": { "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Resolución no encontrada para la empresa autenticada" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Resoluciones DIAN" ], "summary": "Actualizar resolución DIAN", "operationId": "08042c177b5b3e42d3056838722150ba", "parameters": [ { "name": "id", "in": "path", "description": "ID de la resolución a actualizar", "required": true, "schema": { "type": "integer", "example": 1 } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "description": "records: JSON serializado con la resolución completa", "required": true, "content": { "application/json": { "schema": { "required": [ "records" ], "properties": { "records": { "description": "JSON serializado con la resolución completa (no es parcial). Si falta o no es JSON: 422 «El campo records es requerido» / «El campo records debe ser un JSON válido».", "type": "string", "format": "json", "example": "{\"type_document_id\":7,\"resolution_number\":\"18760000001\",\"prefix\":\"SETP\",\"invoice_name\":\"FACTURA ELECTRÓNICA DE VENTA ACTUALIZADA\",\"range_from\":990000000,\"range_up\":995000000,\"date_from\":\"2026-01-01\",\"date_up\":\"2027-12-31\",\"initial_number\":990000000,\"active\":1,\"technical_key\":\"fc8eac422eba16e22ffd8c6f94b3f40a6e38162c\",\"headerline1\":\"\",\"headerline2\":\"\",\"footline1\":\"\",\"footline2\":\"\",\"footline3\":\"\",\"footline4\":\"\"}" } }, "type": "object" } } } }, "responses": { "200": { "description": "Resolución actualizada. Sin message", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true } }, "type": "object" }, "example": { "success": true } } } }, "422": { "description": "Fallo de validación: invoice_name o resolution_number vacíos o demasiado largos (120 / 20), o prefix de más de 20 caracteres", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Validación fallida" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "success": { "type": "boolean", "description": "Solo en la validación de los campos de records", "example": false } }, "type": "object" }, "examples": { "records_invalido": { "summary": "records ausente o no es JSON", "value": { "message": "El campo records es requerido", "errors": { "records": [ "El campo records es requerido" ] } } }, "campos": { "summary": "Campos de records", "value": { "message": "Validación fallida", "errors": { "invoice_name": [ "El campo invoice_name no debe exceder 120 caracteres" ] }, "success": false } } } } } }, "500": { "description": "Falta un campo obligatorio de records o el id no existe" } }, "security": [ { "bearerAuth": [] } ], "description": "Reemplaza los datos de la resolución: no es una actualización parcial. Dentro de records deben venir siempre type_document_id, invoice_name, range_from, range_up, date_from y date_up (si falta alguno responde 500). Los campos omitidos toman su valor por defecto: prefix, resolution_number, technical_key, encabezados y pies vacíos, initial_number 1 y active 1. type_document_id no se puede cambiar (se ignora). Un id inexistente responde 500." }, "delete": { "tags": [ "Resoluciones DIAN" ], "summary": "Eliminar resolución DIAN", "operationId": "792cafaa17e2e716887a4c72cd7e1f00", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Resolución eliminada exitosamente" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/company/templates": { "get": { "tags": [ "Company Templates" ], "summary": "Lista templates asignados a la empresa", "description": "GET /api/company/templates Lista templates asignados a la empresa", "operationId": "f8f74c0aa6d2052d15c43ae385765821", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Lista de templates asignados", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "dataRecords": { "type": "object" } }, "type": "object" } } } } }, "security": [ { "passport": [] } ] } }, "/api/ubl2.1/company/templates/available": { "get": { "tags": [ "Company Templates" ], "summary": "Templates disponibles para asignar", "description": "GET /api/company/templates/available Lista templates del sistema disponibles para asignar", "operationId": "e817d8a76725d31c5263f5bcd9248693", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Lista de templates disponibles", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "dataRecords": { "type": "object" } }, "type": "object" } } } } }, "security": [ { "passport": [] } ] } }, "/api/ubl2.1/company/templates/assign": { "post": { "tags": [ "Company Templates" ], "summary": "Asigna template a empresa", "description": "POST /api/company/templates/assign Asigna template del sistema a empresa", "operationId": "cbe483110aa4eb0bdd0bac53414b0100", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "template_uuid" ], "properties": { "template_uuid": { "type": "string", "example": "uuid-del-template" }, "is_default": { "type": "boolean", "example": true }, "custom_config": { "type": "object" } }, "type": "object" } } } }, "responses": { "201": { "description": "Template asignado exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" } }, "type": "object" } } } } }, "security": [ { "passport": [] } ] } }, "/api/ubl2.1/company/templates/{id}": { "put": { "tags": [ "Company Templates" ], "summary": "Actualiza configuración de asignación", "description": "PUT /api/company/templates/{id} Actualiza configuración de asignación", "operationId": "009b554a6842ff434cc783ea9eedffe3", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "is_default": { "type": "boolean" }, "custom_config": { "type": "object" }, "is_active": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Configuración actualizada" } }, "security": [ { "passport": [] } ] }, "delete": { "tags": [ "Company Templates" ], "summary": "Desasigna template de empresa", "description": "DELETE /api/company/templates/{id} Desasigna template de la empresa", "operationId": "735a3b2c200075b9c87602beace8a409", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Template desasignado" } }, "security": [ { "passport": [] } ] } }, "/api/ubl2.1/company/templates/{id}/customize": { "post": { "tags": [ "Company Templates" ], "summary": "Personaliza template", "description": "POST /api/company/templates/{id}/customize Guarda contenido custom en disco", "operationId": "6aec5b48e553ab964f2573f5a0f19a49", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "blade_content" ], "properties": { "blade_content": { "type": "string" }, "css_content": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Template personalizado guardado" } }, "security": [ { "passport": [] } ] } }, "/api/ubl2.1/company/templates/{id}/clone-for-edit": { "post": { "tags": [ "Company Templates" ], "summary": "Clona template para edición", "description": "POST /api/company/templates/{id}/clone-for-edit Clona template para edición", "operationId": "55cf5b26e8dc7ae4feb2af982bd57f94", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Contenido del template clonado", "content": { "application/json": { "schema": { "properties": { "blade_content": { "type": "string" }, "css_content": { "type": "string" }, "template_name": { "type": "string" } }, "type": "object" } } } } }, "security": [ { "passport": [] } ] } }, "/api/ubl2.1/company/templates/{id}/custom": { "delete": { "tags": [ "Company Templates" ], "summary": "Elimina personalización", "description": "DELETE /api/company/templates/{id}/custom Elimina customización (vuelve a base)", "operationId": "39436f0d792e9f3f102e8e8536a74b06", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Personalización eliminada" } }, "security": [ { "passport": [] } ] } }, "/api/ubl2.1/company/templates/{id}/preview": { "get": { "tags": [ "Company Templates" ], "summary": "Vista previa del template", "description": "GET /api/company/templates/{id}/preview Genera vista previa del template", "operationId": "23890c1800f7ae5d9d4c55bd25641571", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Vista previa generada", "content": { "application/json": { "schema": { "properties": { "html": { "type": "string" }, "css_path": { "type": "string" }, "template_name": { "type": "string" }, "is_custom": { "type": "boolean" } }, "type": "object" } } } } }, "security": [ { "passport": [] } ] } }, "/api/ubl2.1/software": { "get": { "tags": [ "Software DIAN" ], "summary": "Listar software DIAN", "operationId": "b736471ada155c4f27045feed7aae819", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Lista de software obtenida exitosamente" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Software DIAN" ], "summary": "Crear software DIAN", "operationId": "4a8f20014f85c6f87f145d862d3cc9ae", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "records" ], "properties": { "records": { "description": "JSON stringificado con los datos del software", "type": "string" }, "companyId": { "description": "ID de la compañía", "type": "integer", "example": 1, "nullable": true }, "identification": { "description": "ID del software asignado por la DIAN", "type": "string", "example": "96ab0f7c-2ab0-4de4-8c30-1268e6c8c6c3" }, "pin": { "description": "PIN del software asignado por la DIAN", "type": "string", "example": "12345" }, "url": { "description": "URL del servicio web de la DIAN", "type": "string", "example": "https://vpfe-hab.dian.gov.co/WcfDianCustomerServices.svc", "nullable": true }, "environment_id": { "description": "ID del ambiente (1=Producción, 2=Habilitación)", "type": "integer", "example": 2, "nullable": true }, "type_id": { "description": "Tipo de software (1=Propio, 2=Terceros)", "type": "integer", "example": 1, "nullable": true }, "integration_type": { "description": "Tipo de integración", "type": "integer", "example": 1, "nullable": true }, "testsetid": { "description": "ID del set de pruebas", "type": "string", "nullable": true }, "technical_key": { "description": "Clave técnica", "type": "string", "example": "fc8eac422eba16e22ffd8c6f94b3f40a6e38162c", "nullable": true }, "account_id": { "description": "ID de cuenta para integración", "type": "string", "nullable": true }, "auth_token": { "description": "Token de autenticación para integración", "type": "string", "nullable": true }, "initial_number": { "description": "Número inicial para documentos", "type": "integer", "example": 1, "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Software creado exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Software registrado exitosamente" }, "data": { "properties": { "id": { "type": "integer", "example": 1 }, "identification": { "type": "string" }, "pin": { "type": "string" }, "environment_id": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Datos inválidos o software duplicado", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No se encontró la compañía" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/software/process/{id}": { "get": { "tags": [ "Software DIAN" ], "summary": "Obtener software de producción", "operationId": "82c9d8312bb818244ab184256df29f44", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Software de producción obtenido exitosamente" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/software/test/{id}": { "get": { "tags": [ "Software DIAN" ], "summary": "Obtener software de pruebas", "operationId": "e665953ad7cf4b8c255cb130f72cb67c", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Software de pruebas obtenido exitosamente" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/software/{id}": { "get": { "tags": [ "Software DIAN" ], "summary": "Obtener software DIAN por ID", "operationId": "54c8135b6e00ed3116164249e9a48692", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Software obtenido exitosamente" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Software DIAN" ], "summary": "Actualizar software DIAN", "operationId": "203418ecd2f8f491a30eb70ef444c3db", "parameters": [ { "name": "id", "in": "path", "description": "ID del software a actualizar", "required": true, "schema": { "type": "integer", "example": 1 } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "records" ], "properties": { "records": { "description": "JSON stringificado con los datos a actualizar", "type": "string" }, "identification": { "description": "ID del software asignado por la DIAN", "type": "string" }, "pin": { "description": "PIN del software", "type": "string" }, "url": { "description": "URL del servicio web de la DIAN", "type": "string" }, "environment_id": { "description": "ID del ambiente (1=Producción, 2=Habilitación)", "type": "integer" }, "type_id": { "description": "Tipo de software", "type": "integer" }, "integration_type": { "description": "Tipo de integración", "type": "integer" }, "testsetid": { "description": "ID del set de pruebas", "type": "string" }, "technical_key": { "description": "Clave técnica", "type": "string" }, "account_id": { "description": "ID de cuenta para integración", "type": "string" }, "auth_token": { "description": "Token de autenticación", "type": "string" }, "initial_number": { "description": "Número inicial para documentos", "type": "integer" } }, "type": "object" } } } }, "responses": { "200": { "description": "Software actualizado exitosamente", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Software actualizado correctamente" }, "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Software no encontrado", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Software not found" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Software DIAN" ], "summary": "Eliminar software DIAN", "operationId": "bb7952e1b7d634f52adc5fa05442526d", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Software eliminado exitosamente" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ubl2.1/tax-rates": { "get": { "tags": [ "Impuestos" ], "summary": "Obtener tarifas de impuestos", "operationId": "e54614090218383ea4dc2ddf73f7b014", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Tarifas de impuestos obtenidas exitosamente" } } } }, "/api/ubl2.1/taxes": { "get": { "tags": [ "Impuestos" ], "summary": "Obtener lista de impuestos", "operationId": "5a098671c27bffdec672c7300bae2cd5", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Impuestos obtenidos exitosamente" } } } }, "/api/ubl2.1/accounting-regime": { "get": { "tags": [ "Impuestos" ], "summary": "Obtener régimen contable", "operationId": "37a7bf64d390cc19ff60c1e253336eb6", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Régimen contable obtenido exitosamente" } } } }, "/api/ubl2.1/fiscal-regime": { "get": { "tags": [ "Impuestos" ], "summary": "Obtener régimen fiscal", "operationId": "7456cd9f61caaa92b632544fe3440e16", "parameters": [ { "name": "client_uuid", "in": "query", "description": "UUID del cliente asociado a una cuenta principal (opcional). Permite realizar procesos en nombre de cada cliente usando el token de la cuenta principal/casa de software.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "f0456784-69c4-11f1-abf9-d843ae899220" } } ], "responses": { "200": { "description": "Régimen fiscal obtenido exitosamente" } } } } }, "components": { "schemas": { "AttachmentItem": { "description": "Archivo adjunto codificado en base64 para enviar junto al documento por correo electrónico. Máximo 4 adjuntos por request, 2 MB por archivo, 8 MB total.", "required": [ "filename", "content" ], "properties": { "filename": { "description": "Nombre del archivo con extensión", "type": "string", "maxLength": 255, "example": "soporte_pago.pdf" }, "content": { "description": "Contenido del archivo codificado en base64", "type": "string", "format": "byte", "example": "JVBERi0xLjQKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZw..." }, "content_type": { "description": "Tipo MIME del archivo. Tipos permitidos: application/pdf, image/png, image/jpeg, image/gif, text/plain, text/csv, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.wordprocessingml.document", "type": "string", "maxLength": 100, "example": "application/pdf" } }, "type": "object" }, "UserAttachments": { "description": "Array opcional de archivos adjuntos del usuario (máximo 4). Estos archivos se adjuntarán al correo electrónico del documento.", "type": "array", "items": { "$ref": "#/components/schemas/AttachmentItem" }, "maxItems": 4 }, "BulkDocumentItem": { "description": "Documento individual dentro de un lote bulk", "required": [ "kind", "payload" ], "type": "object", "allOf": [ { "$ref": "#/components/schemas/UserAttachments" }, { "properties": { "kind": { "description": "Tipo de documento electrónico", "type": "string", "enum": [ "invoice", "credit_note", "debit_note", "support_document", "adjustment_note", "pos_document" ], "example": "invoice" }, "payload": { "description": "Payload del documento. Mismo formato que el endpoint unitario correspondiente (POST /invoices, POST /credit-notes, etc.)", "type": "object" }, "uuid": { "description": "UUID anti-duplicados del documento. Debe ser un UUID válido y distinto dentro del lote; tiene prioridad sobre payload.uuid. No se reutiliza: si la empresa ya emitió un documento con ese uuid, el item termina FAILED con DUPLICATE_DOCUMENT_UUID y no se emite de nuevo.", "type": "string", "format": "uuid", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "nullable": true }, "client_reference": { "description": "Referencia del cliente para tracking", "type": "string", "maxLength": 64, "example": "FACT-001", "nullable": true }, "attachments": { "description": "Archivos adjuntos del documento (máximo 4). Cada uno exige filename (máx. 255) y content (base64); content_type es opcional (máx. 100).", "type": "array", "items": { "$ref": "#/components/schemas/AttachmentItem" }, "maxItems": 4, "nullable": true } }, "type": "object" } ] }, "BulkBatchResponse": { "description": "Respuesta de estado de un lote bulk", "type": "object", "allOf": [ { "$ref": "#/components/schemas/UserAttachments" }, { "properties": { "batch_id": { "description": "Identificador único del lote", "type": "string", "format": "uuid" }, "status": { "description": "Estado actual del lote. Un lote cortado por stop_on_error termina en PARTIAL o FAILED; un lote FAILED o PARTIAL puede tener documentos que sí llegaron a la DIAN (REJECTED_BY_DIAN, POSSIBLY_SENT).", "type": "string", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "PARTIAL", "FAILED" ] }, "status_description": { "description": "Descripción legible del estado", "type": "string", "example": "Completado" }, "mode": { "description": "Modo de consecutivo", "type": "string", "enum": [ "auto-increment", "manual" ] }, "received": { "description": "Total de documentos recibidos", "type": "integer" }, "succeeded": { "description": "Documentos procesados exitosamente", "type": "integer" }, "failed": { "description": "Documentos FAILED, REJECTED_BY_DIAN y POSSIBLY_SENT (los CANCELLED no suman aquí ni en succeeded)", "type": "integer" }, "created_at": { "description": "Fecha de creación del lote", "type": "string", "format": "date-time" }, "finished_at": { "description": "Fecha de finalización del lote", "type": "string", "format": "date-time", "nullable": true } }, "type": "object" } ] }, "BulkBatchItemResponse": { "description": "Respuesta de estado de un item individual del lote", "type": "object", "allOf": [ { "$ref": "#/components/schemas/UserAttachments" }, { "properties": { "item_id": { "description": "Identificador único del item", "type": "string", "format": "uuid" }, "index": { "description": "Índice del item en el lote (0-based)", "type": "integer" }, "kind": { "description": "Tipo de documento", "type": "string" }, "kind_description": { "description": "Descripción del tipo", "type": "string", "example": "Factura electrónica" }, "client_reference": { "description": "Referencia del cliente", "type": "string", "nullable": true }, "status": { "description": "Estado del item. SUCCESS y REJECTED_BY_DIAN los decide la respuesta DIAN (IsValid/StatusCode), no el código HTTP; en habilitación SUCCESS significa recibido (ZipKey).", "type": "string", "enum": [ "QUEUED", "PROCESSING", "SUCCESS", "FAILED", "REJECTED_BY_DIAN", "POSSIBLY_SENT", "CANCELLED" ] }, "status_description": { "description": "Descripción legible del estado", "type": "string" }, "attempts": { "description": "Número de intentos de procesamiento registrados (1 normalmente; hasta 3 con fallos transitorios)", "type": "integer" }, "error_code": { "description": "Ver error.code", "type": "string", "nullable": true }, "error_message": { "description": "Mensaje del error (máx. 500 caracteres)", "type": "string", "nullable": true }, "processed_at": { "description": "Fecha de procesamiento", "type": "string", "format": "date-time", "nullable": true }, "document_number": { "description": "Número del documento (status SUCCESS, REJECTED_BY_DIAN o POSSIBLY_SENT)", "type": "string", "nullable": true }, "document_uuid": { "description": "UUID del envío del documento; es el que se debe guardar para consultarlo", "type": "string", "format": "uuid", "nullable": true }, "cufe": { "description": "CUFE/XmlDocumentKey del documento (status SUCCESS, REJECTED_BY_DIAN o POSSIBLY_SENT)", "type": "string", "nullable": true }, "track_id": { "description": "Track ID de la DIAN (status SUCCESS, REJECTED_BY_DIAN o POSSIBLY_SENT)", "type": "string", "nullable": true }, "dian_response": { "description": "Resumen de la respuesta DIAN: is_valid, status_code, status, errors, notifications", "type": "object", "nullable": true }, "response": { "description": "JSON (string) con el resumen del resultado: uuid, document_number, XmlDocumentKey, cufe, track_id, is_valid, status_code (código HTTP entero), dian_status_code (código DIAN, p. ej. '00'), dian_status, errors, notifications, warnings, http_status. Sin XML, PDF ni QR en base64 y sin la clave raw del formato anterior", "type": "string", "nullable": true }, "error": { "description": "Detalle del error (status FAILED, REJECTED_BY_DIAN o POSSIBLY_SENT)", "properties": { "code": { "description": "FAILED: código HTTP como string ('400', '404', '409', '422'...), DUPLICATE_DOCUMENT_UUID, JOB_FAILED o STUCK. REJECTED_BY_DIAN: StatusCode de la DIAN o 'DIAN'. POSSIBLY_SENT: DOCUMENT_POSSIBLY_SENT", "type": "string" }, "message": { "description": "Mensaje de error", "type": "string" } }, "type": "object", "nullable": true }, "next_action": { "description": "Solo en POSSIBLY_SENT: consultar el estado con document_uuid; no reenviar", "type": "string", "enum": [ "CHECK_STATUS" ], "nullable": true } }, "type": "object" } ] }, "Webhook": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/UserAttachments" }, { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Webhook Principal" }, "url": { "type": "string", "format": "uri", "example": "https://n8n.cliente.com/webhook/apidian" }, "events": { "type": "array", "items": { "type": "string", "example": "document.created" } }, "headers": { "type": "object", "example": { "Authorization": "Bearer token" }, "nullable": true }, "secret": { "type": "string", "example": "whsec_kJ8x3nQ9mP2vR5tY7wA1bC4dE6fG8hI0jK" }, "is_active": { "type": "boolean", "example": true }, "last_triggered_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } ] }, "WebhookStats": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/UserAttachments" }, { "properties": { "total_deliveries": { "type": "integer", "example": 150 }, "successful": { "type": "integer", "example": 145 }, "failed": { "type": "integer", "example": 5 }, "pending": { "type": "integer", "example": 0 }, "retrying": { "type": "integer", "example": 0 } }, "type": "object" } ] }, "WebhookDelivery": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/UserAttachments" }, { "properties": { "id": { "type": "integer", "example": 42 }, "event_type": { "type": "string", "example": "document.created" }, "status": { "type": "string", "enum": [ "pending", "delivered", "failed", "retrying" ] }, "http_status": { "type": "integer", "example": 200, "nullable": true }, "retry_count": { "type": "integer", "example": 0 }, "payload": { "type": "object" }, "response_body": { "type": "string", "nullable": true }, "delivered_at": { "type": "string", "format": "date-time", "nullable": true }, "next_retry_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" } ] }, "MailboxRetryError": { "description": "No se puede reintentar el correo. 422: MAILBOX_RETRY_NOT_RETRYABLE (IGNORED por virus, otro NIT, sin XML o topes; o UNMATCHED).", "type": "object", "allOf": [ { "$ref": "#/components/schemas/UserAttachments" }, { "properties": { "success": { "description": "Bandeja del buzón de recepción: lectura, reintento de un correo y cupo.", "type": "boolean", "example": false }, "message": { "type": "string", "example": "Este correo llegó antes de que se guardara su ubicación: no se puede reintentar. Pida al proveedor que lo envíe de nuevo." }, "error_code": { "type": "string", "enum": [ "MAILBOX_RETRY_UNAVAILABLE", "MAILBOX_RETRY_NO_LOCATION", "MAILBOX_RETRY_EXPIRED", "MAILBOX_RETRY_IN_PROGRESS", "MAILBOX_ALREADY_PROCESSED", "MAILBOX_RETRY_NOT_RETRYABLE" ] } }, "type": "object" } ] }, "InvoiceRequest": { "title": "Petición de Factura con Consecutivo Automático", "description": "Cuerpo de la petición para crear cualquier tipo de documento electrónico con numeración automática.", "required": [ "resolution_number", "type_document_id", "payments", "customer", "lines", "legal_monetary_totals" ], "properties": { "resolution_number": { "description": "Número de la resolución de facturación activa.", "type": "string", "example": "18764074347312" }, "prefix": { "description": "Prefijo de la resolución, si aplica.", "type": "string", "example": "SETP", "nullable": true }, "companyId": { "description": "Opcional. UUID de la empresa cliente (para desarrolladores con múltiples clientes).", "type": "string", "format": "uuid", "example": "9d115e84-1cfa-42f8-a1dd-93339393e114", "nullable": true }, "notes": { "description": "Observaciones generales del documento.", "type": "string", "example": "Factura de prueba con items.", "nullable": true }, "report_header": { "$ref": "#/components/schemas/ReportHeader" }, "send_email": { "description": "Indica si se debe enviar el correo al adquiriente.", "type": "boolean", "example": true }, "operation_type_id": { "description": "ID del tipo de operación.", "type": "integer", "example": 1 }, "type_document_id": { "description": "ID del tipo de documento a generar (ej. 7 para Factura).", "type": "integer", "example": 7 }, "payments": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, "order_reference": { "$ref": "#/components/schemas/OrderReference" }, "document_signature": { "$ref": "#/components/schemas/DocumentSignature" }, "customer": { "$ref": "#/components/schemas/Customer" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceLine" } }, "legal_monetary_totals": { "$ref": "#/components/schemas/LegalMonetaryTotals" }, "tax_totals": { "type": "array", "items": { "$ref": "#/components/schemas/TaxTotal" }, "nullable": true }, "health": { "oneOf": [ { "$ref": "#/components/schemas/HealthRequest" } ], "nullable": true, "description": "Información del Sector Salud. Opcional; requerido únicamente para Documento Soporte del sector salud.", "type": "object" } }, "type": "object" }, "HealthRequest": { "title": "Información del Sector Salud", "description": "Bloque opcional. Si se envía, `operation_type`, `provider_code`, `payment_modality`, `coverage` e `invoice_period` son obligatorios.", "properties": { "operation_type": { "type": "string", "example": "10" }, "provider_code": { "description": "Código del prestador de servicios de salud.", "type": "string", "example": "12345" }, "payment_modality": { "type": "string", "example": "01" }, "coverage": { "type": "string", "example": "01" }, "contract_number": { "description": "Número de contrato. Si no se envía, `justification_without_contract` es obligatorio.", "type": "string", "example": "CT-2026-001", "nullable": true }, "justification_without_contract": { "description": "Requerido cuando no se envía contract_number.", "type": "string", "maxLength": 2, "example": "01", "nullable": true }, "policy_number": { "type": "string", "example": "POL-2026-001", "nullable": true }, "copayment": { "description": "COPAGO. Sin símbolos ni separadores de miles; punto como separador decimal.", "type": "number", "format": "float", "example": 5000, "nullable": true }, "moderator_fee": { "description": "CUOTA_MODERADORA. Sin símbolos ni separadores de miles; punto como separador decimal.", "type": "number", "format": "float", "example": 2000, "nullable": true }, "shared_payments": { "description": "PAGOS_COMPARTIDOS. Sin símbolos ni separadores de miles; punto como separador decimal.", "type": "number", "format": "float", "example": 0, "nullable": true }, "advance": { "description": "ANTICIPO. Sin símbolos ni separadores de miles; punto como separador decimal.", "type": "number", "format": "float", "example": 0, "nullable": true }, "invoice_period": { "$ref": "#/components/schemas/HealthInvoicePeriod" }, "download_attachments": { "oneOf": [ { "$ref": "#/components/schemas/HealthServiceCall" } ], "nullable": true, "type": "object" }, "document_delivery": { "oneOf": [ { "$ref": "#/components/schemas/HealthServiceCall" } ], "nullable": true, "type": "object" } }, "type": "object" }, "HealthInvoicePeriod": { "title": "Periodo de Facturación del Servicio de Salud", "properties": { "start_date": { "type": "string", "format": "date", "example": "2026-08-01" }, "start_time": { "type": "string", "example": "00:00:00" }, "end_date": { "type": "string", "format": "date", "example": "2026-08-31" }, "end_time": { "type": "string", "example": "23:59:59" } }, "type": "object" }, "HealthServiceCall": { "title": "Llamado a Servicio Web (descarga de soportes o entrega del documento)", "properties": { "url": { "description": "Solo aplica para download_attachments.", "type": "string", "example": "https://example.com/soportes.zip", "nullable": true }, "ws": { "description": "Solo aplica para document_delivery.", "type": "string", "format": "url", "example": "https://example.com/ws/entrega", "nullable": true }, "arguments": { "type": "array", "items": { "properties": { "name": { "type": "string", "example": "usuario" }, "value": { "type": "string", "example": "valor" } }, "type": "object" } } }, "type": "object" }, "ReportHeader": { "title": "Encabezado del Reporte", "properties": { "uuid": { "type": "string", "example": "101413670038274164" }, "vars": { "type": "array", "items": { "properties": { "name": { "type": "string" }, "value": { "type": "string" } }, "type": "object" } } }, "type": "object" }, "Payment": { "title": "Información de Pago", "properties": { "payment_method_id": { "type": "integer", "example": 1 }, "means_payment_id": { "type": "integer", "example": 10 }, "value_paid": { "type": "number", "format": "float", "example": 224 } }, "type": "object" }, "OrderReference": { "title": "Referencia de la Orden", "properties": { "reference_number": { "type": "string", "example": "4541212" }, "reference_date": { "type": "string", "format": "date", "example": "2025-06-01" } }, "type": "object" }, "DocumentSignature": { "title": "Firmas del Documento", "properties": { "cashier": { "type": "string", "example": "Nombre del cajero(a)" }, "seller": { "type": "string", "example": "Nombre del vendedor(a)" } }, "type": "object" }, "Customer": { "title": "Información del Cliente", "properties": { "identity_document_id": { "type": "integer", "example": 3 }, "company_name": { "type": "string", "example": "CLIENTE EJEMPLO SAS" }, "dni": { "type": "string", "example": "900000000" }, "email": { "type": "string", "format": "email", "example": "cliente@ejemplo.com" } }, "type": "object" }, "InvoiceLine": { "title": "Línea de la Factura", "properties": { "invoiced_quantity": { "type": "number", "format": "float", "example": 2 }, "quantity_units_id": { "type": "integer", "example": 1093 }, "line_extension_amount": { "type": "number", "format": "float", "example": 100 }, "free_of_charge_indicator": { "type": "boolean", "example": false }, "description": { "type": "string", "example": "TIJERA NECROPSIA AVES" }, "code": { "type": "string", "example": "HMT83" }, "type_item_identifications_id": { "type": "integer", "example": 4 }, "price_amount": { "type": "number", "format": "float", "example": 50 }, "base_quantity": { "type": "number", "format": "float", "example": 2 }, "tax_totals": { "type": "array", "items": { "$ref": "#/components/schemas/TaxTotal" } } }, "type": "object" }, "LegalMonetaryTotals": { "title": "Totales Monetarios", "properties": { "line_extension_amount": { "type": "number", "format": "float", "example": 200 }, "tax_exclusive_amount": { "type": "number", "format": "float", "example": 200 }, "tax_inclusive_amount": { "type": "number", "format": "float", "example": 224 }, "payable_amount": { "type": "number", "format": "float", "example": 224 } }, "type": "object" }, "TaxTotal": { "title": "Total de Impuesto", "properties": { "tax_id": { "type": "integer", "example": 1 }, "tax_amount": { "type": "number", "format": "float", "example": 24 }, "taxable_amount": { "type": "number", "format": "float", "example": 200 }, "percent": { "type": "number", "format": "float", "example": 12 } }, "type": "object" }, "EventRequest": { "title": "Solicitud de Evento RADIAN", "description": "Cuerpo de la petición para registrar un evento RADIAN sobre un documento recibido (acuse de recibo, reclamo, recibo del bien, aceptación).", "properties": { "code": { "description": "Código del tipo de evento RADIAN (030=Acuse de recibo de Factura Electrónica de Venta, 031=Reclamo de la Factura Electrónica de Venta, 032=Recibo del bien y/o prestación del servicio, 033=Aceptación expresa, 034=Aceptación Tácita). Cuando code=031, el campo claim_code es obligatorio.", "type": "string", "example": "030" }, "claim_code": { "description": "Obligatorio únicamente cuando code=031. Valores actuales: 01=Documento con inconsistencias, 02=Mercancía no entregada, 03=Mercancía entregada parcialmente, 04=Servicio no prestado.", "type": "string", "example": "01", "nullable": true }, "notes": { "description": "Observaciones del evento", "type": "string", "example": "Acuse de recibo del documento", "nullable": true }, "reception_person_uuid": { "description": "Persona de recepción que firma el evento (GET /events/reception-people). Sin él firma la persona por defecto de la empresa.", "type": "string", "format": "uuid", "nullable": true } }, "type": "object" }, "ReceptionPerson": { "title": "Persona de recepción", "description": "Quien acusa y acepta los documentos recibidos ante la DIAN; sus datos viajan en los eventos RADIAN. No expone el id interno ni el identificador del buzón.", "properties": { "uuid": { "description": "Identificador público; es el que va en las rutas y en reception_person_uuid", "type": "string", "format": "uuid" }, "identity_document_id": { "type": "integer", "example": 3 }, "identity_document": { "properties": { "id": { "type": "integer", "example": 3 }, "code": { "type": "string", "example": "13" }, "name": { "type": "string", "example": "Cédula de ciudadanía" } }, "type": "object", "nullable": true }, "dni": { "type": "string", "example": "1065000000" }, "dv": { "type": "string", "example": "7", "nullable": true }, "first_name": { "type": "string", "example": "Ana" }, "last_name": { "type": "string", "example": "Pérez" }, "email": { "type": "string", "format": "email", "nullable": true }, "job_title": { "type": "string", "example": "Contadora", "nullable": true }, "department": { "type": "string", "example": "Contabilidad", "nullable": true }, "is_default": { "description": "Persona por defecto: firma los eventos automáticos del buzón y guarda el buzón y el modo de la empresa. Exactamente una por empresa", "type": "boolean" }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "ReceptionPeopleState": { "title": "Personas de recepción de la empresa", "properties": { "send_events": { "description": "Modo de la EMPRESA: true = eventos automáticos (030, 032 y 033), false = manuales. Se lee de la persona por defecto; false si no hay personas", "type": "boolean" }, "default_person_uuid": { "description": "Persona por defecto; null si la empresa no tiene personas", "type": "string", "format": "uuid", "nullable": true }, "people": { "description": "Por defecto primero, luego por antigüedad", "type": "array", "items": { "$ref": "#/components/schemas/ReceptionPerson" } } }, "type": "object" }, "ReceptionPersonInput": { "title": "Datos de una persona de recepción", "description": "En POST son obligatorios identity_document_id, dni, first_name y last_name; en PUT todo es opcional (edición parcial). is_default, send_events, email_reception y company_id NO se aceptan (422): son de la empresa y tienen su propio endpoint.", "properties": { "identity_document_id": { "type": "integer", "example": 3 }, "dni": { "type": "string", "maxLength": 20, "example": "1065000000" }, "dv": { "type": "string", "maxLength": 2, "example": "7", "nullable": true }, "first_name": { "type": "string", "maxLength": 60, "example": "Ana" }, "last_name": { "type": "string", "maxLength": 60, "example": "Pérez" }, "email": { "type": "string", "format": "email", "maxLength": 100, "nullable": true }, "job_title": { "type": "string", "maxLength": 100, "example": "Contadora", "nullable": true }, "department": { "type": "string", "maxLength": 100, "example": "Contabilidad", "nullable": true }, "client_uuid": { "description": "UUID de una sub-cuenta propia (Casa de Software). Sin él se usa la empresa del token", "type": "string", "format": "uuid", "nullable": true } }, "type": "object" } }, "responses": { "ReceptionNotInPlan": { "description": "Prohibido. Con error_code RECEPTION_NOT_IN_PLAN: el módulo de recepción (buzón, eventos RADIAN, importación por Excel o CUFE, personas de recepción, ajustes y envío en bloque) es solo para planes de PAGO VIGENTES. Lo reciben el plan FREE y la empresa sin plan vigente (FREE vencida, plan de pago vencido o sin suscripción). Vigente = suscripción con status active y end_date futuro de un plan que no es FREE; el ilimitado (Arrendamiento) y los contratos mensuales o pospago vigentes son de pago y tienen acceso, también sin saldo de documentos. Se evalúa el plan de la Casa de Software si la empresa es sub-cuenta (client_uuid). Un cambio de plan se refleja en la API en máximo 60 s. Sin error_code: el client_uuid no es una sub-cuenta propia o la empresa está inactiva.", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "El plan FREE no incluye la recepción de facturas ni los eventos RADIAN. Actualice su plan para usarlos." }, "error_code": { "description": "Solo en el 403 de plan; el 403 de un client_uuid ajeno no lo trae", "type": "string", "enum": [ "RECEPTION_NOT_IN_PLAN" ], "example": "RECEPTION_NOT_IN_PLAN" } }, "type": "object" } } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "description": "Incluye el token en el header: Authorization: Bearer {token}", "name": "Authorization", "in": "header", "bearerFormat": "JWT", "scheme": "bearer" } } }, "tags": [ { "name": "Envío Masivo (Bulk)", "description": "Endpoints para envío masivo de documentos electrónicos. Permite procesar múltiples facturas, notas crédito, notas débito, documentos soporte, notas de ajuste y documentos POS en un solo request." }, { "name": "Personal Access Tokens", "description": "API endpoints para gestionar Personal Access Tokens (PAT). Permite a los usuarios crear, listar, ver y revocar sus tokens de acceso API." }, { "name": "Webhooks", "description": "API endpoints para gestionar webhooks salientes. Permite a las empresas recibir notificaciones HTTP en tiempo real sobre eventos importantes (documentos, emails, pagos, membresías). Ideal para integraciones con n8n, Zapier, Make y herramientas de automatización." }, { "name": "Eventos de Documentos", "description": "Gestión de eventos y acuse de recibo de documentos electrónicos" }, { "name": "Nómina Electrónica - Tablas", "description": "Tablas maestras para nómina electrónica" }, { "name": "Personas de Recepción", "description": "Personas que acusan y aceptan los documentos recibidos ante la DIAN. Varias por empresa, una por defecto, un solo buzón." }, { "name": "Tablas Maestras", "description": "Endpoints públicos para obtener tablas maestras y catálogos de la DIAN" }, { "name": "Configuración de Reportes", "description": "Configuración de encabezados y pie de página para reportes" }, { "name": "Company Templates", "description": "Gestión de templates de factura por empresa" }, { "name": "Consultas", "description": "Consultas" }, { "name": "Documentos Electrónicos", "description": "Documentos Electrónicos" }, { "name": "Documentos con Consecutivo Automático", "description": "Documentos con Consecutivo Automático" }, { "name": "Nómina Electrónica", "description": "Nómina Electrónica" }, { "name": "Funciones Auxiliares", "description": "Funciones Auxiliares" }, { "name": "Estado de Documentos", "description": "Estado de Documentos" }, { "name": "Autenticación", "description": "Autenticación" }, { "name": "Perfil", "description": "Perfil" }, { "name": "Recuperación de Contraseña", "description": "Recuperación de Contraseña" }, { "name": "Registro", "description": "Registro" }, { "name": "Certificados Digitales", "description": "Certificados Digitales" }, { "name": "Empresa", "description": "Empresa" }, { "name": "Clientes", "description": "Clientes" }, { "name": "Monedas", "description": "Monedas" }, { "name": "Gestión de Documentos", "description": "Gestión de Documentos" }, { "name": "Documentos Enviados", "description": "Documentos Enviados" }, { "name": "Personalización de Correos", "description": "Personalización de Correos" }, { "name": "Buzón de Recepción", "description": "Buzón de Recepción" }, { "name": "Ubicación", "description": "Ubicación" }, { "name": "Registros de Email", "description": "Registros de Email" }, { "name": "Membresías", "description": "Membresías" }, { "name": "Resoluciones DIAN", "description": "Resoluciones DIAN" }, { "name": "Software DIAN", "description": "Software DIAN" }, { "name": "Impuestos", "description": "Impuestos" } ], "externalDocs": { "description": "Documentación completa de MATIAS", "url": "https://docs.matias-api.com/" } }