{ "openapi": "3.1.0", "info": { "title": "API de Trevol", "version": "2026-10-21", "description": "Facturación electrónica de Colombia (DIAN). Cada llave es de una empresa y un ambiente: tvl_test_ (habilitación real de la DIAN) o tvl_live_ (producción). Mensajes en español. Documentación: https://trevol.si/desarrolladores" }, "servers": [ { "url": "https://api.trevol.si/v1" } ], "security": [ { "llave": [] } ], "paths": { "/health": { "get": { "summary": "Salud", "security": [], "responses": { "200": { "description": "ok" } } } }, "/company": { "get": { "summary": "La empresa de la llave", "responses": { "200": { "description": "La empresa, su ambiente y sus numeraciones activas" }, "default": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/dian/acquirer": { "get": { "summary": "Datos del adquiriente en la DIAN", "parameters": [ { "name": "document_type", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "document_number", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{found, name, email}" }, "default": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/invoices": { "post": { "summary": "Emitir una factura", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Obligatoria: 1 a 255 caracteres ASCII visibles, única por pedido (7 días).", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Trevol-Version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "2026-10-21" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceInput" } } } }, "responses": { "201": { "description": "El documento", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "202": { "description": "El documento", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "402": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "get": { "summary": "Listar (factura)", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "external_id", "in": "query", "schema": { "type": "string" } }, { "name": "created_from", "in": "query", "schema": { "type": "string" } }, { "name": "created_to", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "{object: list, data, has_more, next_cursor}" }, "default": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/invoices/preview": { "post": { "summary": "Calcular una factura sin emitirla", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceInput" } } } }, "responses": { "200": { "description": "Totales" }, "default": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/invoices/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Una factura", "responses": { "200": { "description": "El documento", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "default": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "put": { "summary": "Corregir una factura rechazada (mismo número) y reenviarla", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Obligatoria: 1 a 255 caracteres ASCII visibles, única por pedido (7 días).", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Trevol-Version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "2026-10-21" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceInput" } } } }, "responses": { "200": { "description": "El documento", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "default": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/invoices/{id}/send": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Reenviar una pendiente o en error", "responses": { "200": { "description": "El documento", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "default": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/invoices/{id}/pdf": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Archivo pdf", "responses": { "200": { "description": "pdf", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/invoices/{id}/xml": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Archivo xml", "responses": { "200": { "description": "xml", "content": { "application/xml": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/invoices/{id}/zip": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Archivo zip", "responses": { "200": { "description": "zip", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/invoices/{id}/dian_response": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Archivo dian_response", "responses": { "200": { "description": "dian_response", "content": { "application/xml": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/credit_notes": { "post": { "summary": "Emitir una nota crédito", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Obligatoria: 1 a 255 caracteres ASCII visibles, única por pedido (7 días).", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Trevol-Version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "2026-10-21" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteInput" } } } }, "responses": { "201": { "description": "El documento", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "202": { "description": "El documento", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "402": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "get": { "summary": "Listar (nota crédito)", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "external_id", "in": "query", "schema": { "type": "string" } }, { "name": "created_from", "in": "query", "schema": { "type": "string" } }, { "name": "created_to", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "{object: list, data, has_more, next_cursor}" }, "default": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/credit_notes/preview": { "post": { "summary": "Calcular una nota crédito sin emitirla", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteInput" } } } }, "responses": { "200": { "description": "Totales" }, "default": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/credit_notes/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Una nota crédito", "responses": { "200": { "description": "El documento", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "default": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "put": { "summary": "Corregir una nota crédito rechazada (mismo número) y reenviarla", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Obligatoria: 1 a 255 caracteres ASCII visibles, única por pedido (7 días).", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Trevol-Version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "2026-10-21" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteInput" } } } }, "responses": { "200": { "description": "El documento", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "default": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/credit_notes/{id}/send": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Reenviar una pendiente o en error", "responses": { "200": { "description": "El documento", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "default": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/credit_notes/{id}/pdf": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Archivo pdf", "responses": { "200": { "description": "pdf", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/credit_notes/{id}/xml": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Archivo xml", "responses": { "200": { "description": "xml", "content": { "application/xml": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/credit_notes/{id}/zip": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Archivo zip", "responses": { "200": { "description": "zip", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/credit_notes/{id}/dian_response": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Archivo dian_response", "responses": { "200": { "description": "dian_response", "content": { "application/xml": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/debit_notes": { "post": { "summary": "Emitir una nota débito", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Obligatoria: 1 a 255 caracteres ASCII visibles, única por pedido (7 días).", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Trevol-Version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "2026-10-21" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteInput" } } } }, "responses": { "201": { "description": "El documento", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "202": { "description": "El documento", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "402": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "get": { "summary": "Listar (nota débito)", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "external_id", "in": "query", "schema": { "type": "string" } }, { "name": "created_from", "in": "query", "schema": { "type": "string" } }, { "name": "created_to", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "{object: list, data, has_more, next_cursor}" }, "default": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/debit_notes/preview": { "post": { "summary": "Calcular una nota débito sin emitirla", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteInput" } } } }, "responses": { "200": { "description": "Totales" }, "default": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/debit_notes/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Una nota débito", "responses": { "200": { "description": "El documento", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "default": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "put": { "summary": "Corregir una nota débito rechazada (mismo número) y reenviarla", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Obligatoria: 1 a 255 caracteres ASCII visibles, única por pedido (7 días).", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Trevol-Version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "2026-10-21" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteInput" } } } }, "responses": { "200": { "description": "El documento", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "default": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/debit_notes/{id}/send": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Reenviar una pendiente o en error", "responses": { "200": { "description": "El documento", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "default": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/debit_notes/{id}/pdf": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Archivo pdf", "responses": { "200": { "description": "pdf", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/debit_notes/{id}/xml": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Archivo xml", "responses": { "200": { "description": "xml", "content": { "application/xml": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/debit_notes/{id}/zip": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Archivo zip", "responses": { "200": { "description": "zip", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/debit_notes/{id}/dian_response": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Archivo dian_response", "responses": { "200": { "description": "dian_response", "content": { "application/xml": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "Error (application/problem+json)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } } }, "components": { "securitySchemes": { "llave": { "type": "http", "scheme": "bearer", "description": "tvl_test_… o tvl_live_…" } }, "schemas": { "Customer": { "type": "object", "additionalProperties": false, "properties": { "final_consumer": { "type": "boolean" }, "document_type": { "type": "string", "maxLength": 20, "description": "Tipo de documento (tabla 13.2.1 de la DIAN): 13 CC, 31 NIT, 22 CE, 41 PA…" }, "document_number": { "type": "string", "description": "Sin DV ni puntos; el DV lo calcula Trevol." }, "check_digit": { "type": "integer", "description": "Opcional: si viene, tiene que ser el DV del NIT." }, "name": { "type": "string" }, "person_type": { "type": "string", "enum": [ "legal", "natural" ], "description": "Por defecto se deduce del NIT." }, "email": { "type": "string" }, "phone": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "municipality_code": { "type": "string", "maxLength": 20, "description": "Código DANE del municipio (5 dígitos)." }, "department_code": { "type": "string", "maxLength": 20 }, "tax_responsibilities": { "type": "array", "items": { "type": "string" }, "maxItems": 20, "description": "Tabla 13.2.6.1 (O-13, O-15, O-23, O-47, R-99-PN)." }, "tax_scheme": { "type": "string", "maxLength": 20, "description": "TaxScheme del adquiriente: 01, 04, ZA o ZZ (por defecto ZZ)." } } }, "ItemTax": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string", "maxLength": 20, "description": "Código (texto)." }, "rate": { "oneOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Tarifa en % (ICA y ReteICA: por mil)." }, "excluded": { "type": "boolean" }, "unit_amount": { "oneOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Número o texto decimal con punto («150000.50»)." }, "unit": { "type": "string", "maxLength": 20, "description": "Unidad de medida (tabla 13.3.6). Por defecto 94 (unidad)." }, "quantity": { "oneOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Número o texto decimal con punto («150000.50»)." }, "volume_cc": { "oneOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Número o texto decimal con punto («150000.50»)." }, "name": { "type": "string" } }, "required": [ "code" ] }, "ItemAllowance": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string", "maxLength": 20, "description": "Código (texto)." }, "reason": { "type": "string" }, "percent": { "oneOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Número o texto decimal con punto («150000.50»)." }, "amount": { "oneOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Número o texto decimal con punto («150000.50»)." } } }, "ItemWithholding": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string", "maxLength": 20, "description": "Código (texto)." }, "rate": { "oneOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Tarifa en % (ICA y ReteICA: por mil)." }, "self_withholding": { "type": "boolean" } }, "required": [ "code", "rate" ] }, "Withholding": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string", "maxLength": 20, "description": "Código (texto)." }, "rate": { "oneOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Tarifa en % (ICA y ReteICA: por mil)." }, "self_withholding": { "type": "boolean" }, "base": { "oneOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Número o texto decimal con punto («150000.50»)." } }, "required": [ "code", "rate" ] }, "FreeOfCharge": { "type": "object", "additionalProperties": false, "properties": { "reference_price": { "oneOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Número o texto decimal con punto («150000.50»)." }, "price_type": { "type": "string", "maxLength": 20 } } }, "StandardCode": { "type": "object", "additionalProperties": false, "properties": { "scheme": { "type": "string", "maxLength": 20 }, "value": { "type": "string" } } }, "Item": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string", "description": "Código (texto)." }, "description": { "type": "string" }, "unit": { "type": "string", "maxLength": 20, "description": "Unidad de medida (tabla 13.3.6). Por defecto 94 (unidad)." }, "quantity": { "oneOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Número o texto decimal con punto («150000.50»)." }, "unit_price": { "oneOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Precio unitario SIN impuestos." }, "taxes": { "type": "array", "items": { "$ref": "#/components/schemas/ItemTax" }, "maxItems": 12, "description": "Impuestos de la línea: {code, rate} porcentual, {code: \"01\", excluded: true} o nominal {code, unit_amount, unit?, quantity?}." }, "discounts": { "type": "array", "items": { "$ref": "#/components/schemas/ItemAllowance" }, "maxItems": 10 }, "charges": { "type": "array", "items": { "$ref": "#/components/schemas/ItemAllowance" }, "maxItems": 10 }, "withholdings": { "type": "array", "items": { "$ref": "#/components/schemas/ItemWithholding" }, "maxItems": 10, "description": "Retenciones (informativas): 05 ReteIVA, 06 ReteRenta, 07 ReteICA." }, "free_of_charge": { "$ref": "#/components/schemas/FreeOfCharge" }, "standard_code": { "$ref": "#/components/schemas/StandardCode" }, "brand": { "type": "string" }, "model": { "type": "string" } }, "required": [ "description", "quantity", "unit_price" ] }, "PaymentMethod": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string", "maxLength": 20, "description": "Código (texto)." }, "reference": { "type": "string" } }, "required": [ "code" ] }, "Payment": { "type": "object", "additionalProperties": false, "properties": { "form": { "type": "string", "enum": [ "cash", "credit" ], "description": "cash (contado) | credit (crédito: con due_date o term_days)." }, "term_days": { "type": "integer" }, "due_date": { "type": "string", "format": "date" }, "methods": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethod" }, "maxItems": 5, "description": "Medios de pago (tabla 13.3.4.2): 10 efectivo, 42 consignación, 47 transferencia…" } }, "required": [ "form" ] }, "Period": { "type": "object", "additionalProperties": false, "properties": { "start": { "type": "string", "format": "date" }, "end": { "type": "string", "format": "date" } } }, "DocumentReference": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "date": { "type": "string", "format": "date" } } }, "References": { "type": "object", "additionalProperties": false, "properties": { "purchase_order": { "$ref": "#/components/schemas/DocumentReference" }, "despatches": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentReference" }, "maxItems": 20 }, "receipts": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentReference" }, "maxItems": 20 } } }, "AllowanceCharge": { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "discount", "charge" ] }, "code": { "type": "string", "maxLength": 20, "description": "Código (texto)." }, "reason": { "type": "string" }, "percent": { "oneOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Número o texto decimal con punto («150000.50»)." }, "amount": { "oneOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Número o texto decimal con punto («150000.50»)." }, "base": { "oneOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Número o texto decimal con punto («150000.50»)." } }, "required": [ "type" ] }, "Prepayment": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "amount": { "oneOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Número o texto decimal con punto («150000.50»)." }, "received_date": { "type": "string", "format": "date" }, "paid_date": { "type": "string", "format": "date" }, "instructions": { "type": "string" } }, "required": [ "id", "amount", "received_date" ] }, "InvoiceReference": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "pattern": "^inv_[0-9a-f]{32}$" } } }, { "type": "object", "additionalProperties": false, "required": [ "number", "cufe", "issue_date" ], "properties": { "number": { "type": "string" }, "cufe": { "type": "string", "pattern": "^[0-9a-fA-F]{96}$" }, "issue_date": { "type": "string", "format": "date" }, "total": { "oneOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Número o texto decimal con punto («150000.50»)." } } } ] }, "InvoiceInput": { "type": "object", "additionalProperties": false, "properties": { "external_id": { "type": "string", "pattern": "^[A-Za-z0-9:._/-]{1,100}$", "description": "Tu identificador del documento: único entre los documentos API de la empresa y el ambiente." }, "customer": { "$ref": "#/components/schemas/Customer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Item" }, "maxItems": 500, "description": "Las líneas (1 a 500)." }, "payment": { "$ref": "#/components/schemas/Payment" }, "notes": { "type": "array", "items": { "type": "string" }, "maxItems": 10 }, "period": { "$ref": "#/components/schemas/Period" }, "references": { "$ref": "#/components/schemas/References" }, "allowance_charges": { "type": "array", "items": { "$ref": "#/components/schemas/AllowanceCharge" }, "maxItems": 20, "description": "Descuentos y recargos globales (no tocan las bases)." }, "prepayments": { "type": "array", "items": { "$ref": "#/components/schemas/Prepayment" }, "maxItems": 20, "description": "Anticipos (informativos: no restan del total)." }, "withholdings": { "type": "array", "items": { "$ref": "#/components/schemas/Withholding" }, "maxItems": 10, "description": "Retenciones (informativas): 05 ReteIVA, 06 ReteRenta, 07 ReteICA." }, "rounding": { "oneOf": [ { "type": "boolean" }, { "oneOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Número o texto decimal con punto («150000.50»)." } ], "description": "true = redondeo al peso; o un valor entre -2.00 y 2.00." } }, "required": [ "items" ] }, "NoteInput": { "type": "object", "additionalProperties": false, "properties": { "external_id": { "type": "string", "pattern": "^[A-Za-z0-9:._/-]{1,100}$", "description": "Tu identificador del documento: único entre los documentos API de la empresa y el ambiente." }, "customer": { "$ref": "#/components/schemas/Customer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Item" }, "maxItems": 500, "description": "Las líneas (1 a 500)." }, "payment": { "$ref": "#/components/schemas/Payment" }, "notes": { "type": "array", "items": { "type": "string" }, "maxItems": 10 }, "period": { "$ref": "#/components/schemas/Period" }, "references": { "$ref": "#/components/schemas/References" }, "allowance_charges": { "type": "array", "items": { "$ref": "#/components/schemas/AllowanceCharge" }, "maxItems": 20, "description": "Descuentos y recargos globales (no tocan las bases)." }, "prepayments": { "type": "array", "items": { "$ref": "#/components/schemas/Prepayment" }, "maxItems": 20, "description": "Anticipos (informativos: no restan del total)." }, "withholdings": { "type": "array", "items": { "$ref": "#/components/schemas/Withholding" }, "maxItems": 10, "description": "Retenciones (informativas): 05 ReteIVA, 06 ReteRenta, 07 ReteICA." }, "rounding": { "oneOf": [ { "type": "boolean" }, { "oneOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Número o texto decimal con punto («150000.50»)." } ], "description": "true = redondeo al peso; o un valor entre -2.00 y 2.00." }, "concept": { "type": "string", "maxLength": 20, "description": "Concepto de corrección: NC 1–6, ND 1–4." }, "description": { "type": "string" }, "invoice": { "$ref": "#/components/schemas/InvoiceReference" } }, "required": [ "items", "concept" ] }, "Document": { "type": "object", "properties": { "id": { "type": "string", "description": "inv_… | cn_… | dn_…" }, "object": { "type": "string", "enum": [ "invoice", "credit_note", "debit_note" ] }, "environment": { "type": "string", "enum": [ "test", "live" ] }, "status": { "type": "string", "enum": [ "pending", "sending", "accepted", "rejected", "error", "contingency" ] }, "number": { "type": [ "string", "null" ] }, "prefix": { "type": [ "string", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "origin": { "type": "string", "enum": [ "api", "app", "contapyme" ] }, "cufe": { "type": [ "string", "null" ] }, "cude": { "type": [ "string", "null" ] }, "qr": { "type": [ "string", "null" ] }, "issued_at": { "type": [ "string", "null" ], "format": "date-time" }, "customer": { "$ref": "#/components/schemas/Customer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Item" } }, "payment": { "$ref": "#/components/schemas/Payment" }, "invoice": { "$ref": "#/components/schemas/InvoiceReference" }, "totals": { "type": [ "object", "null" ], "description": "Montos como texto decimal con 2 decimales." }, "dian": { "type": "object", "properties": { "status_code": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "rules": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "severity": { "type": "string", "enum": [ "rejection", "notification" ] }, "message": { "type": "string" }, "area": { "type": "string" }, "explanation": { "type": "string" }, "fix": { "type": [ "string", "null" ] }, "field": { "type": "string" } } } } } }, "delivery": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Problem": { "type": "object", "required": [ "type", "title", "status", "code", "retryable", "request_id" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string", "enum": [ "authentication_required", "certificate_problem", "company_not_enabled", "dian_rejected", "dian_unavailable", "external_id_in_use", "file_unavailable", "idempotency_key_required", "idempotency_key_reused", "insufficient_balance", "internal_error", "invalid_api_key", "invalid_json", "invalid_request", "invalid_state", "method_not_allowed", "not_found", "numbering_unavailable", "permission_denied", "rate_limited", "request_in_progress", "unsupported_version", "validation_error" ] }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after": { "type": "integer" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "pointer": { "type": "string" }, "message": { "type": "string" } } } }, "document": { "$ref": "#/components/schemas/Document" }, "existing_id": { "type": "string" } } } } } }