Documentación API

Campo	Tipo	Req
Username	string	Sí
Password	string	Sí

Campo	Tipo
Username	string
Password	string

Campo	Tipo	Descripción
ID	string	ID del usuario
Name / LastName	string	Nombre y apellido
Phone / Email	string	Contacto
Username	string	Username de acceso
Token	string	JWT Bearer token
Role	string	Admin \| User \| Sudo \| Broker \| Seller
CompanyKey	string	Código de empresa/tenant

Autenticación: Todos los endpoints (excepto ValidateByCufe) requieren header Authorization: Bearer <token> obtenido desde EB.Api.Security. El tenant se extrae automáticamente del JWT.

📄

DocumentController v1

Base: /api/v1/Document

POST /api/v1/Document User · Admin▼

Procesa un documento electrónico individual. Guarda fuente en storage y dispara transformación XML asíncrona. El tenant se extrae del claim JWT.

Request — DocumentRequest v1 (campos principales)

Campo	Tipo	Req	Descripción
DocumentId	string	Sí	Código único en ERP
Consecutive	long	Sí	Consecutivo del documento
InvoiceTypeCode	TypeDocumentEnum	Sí	Tipo: 1=Venta, 2=Exportación, 3=Contingencia, 5=Soporte, 91=NC, 92=ND, 60=SPD, 100=Adjunto
IssueDate	DateTime	Sí	Fecha de emisión
DocumentCurrencyCode	string	Sí	Moneda (ej: COP)
IsTest	bool	No	Ambiente de pruebas
ResolutionNumber	long	No	Número de resolución
ResolutionPrefix	string	No	Prefijo de resolución
ClientID	string	Sí	Identificación del cliente
ClientIdentificationType	int	Sí	Tipo ID (11=RC,12=TI,13=CC,22=CE,31=NIT,41=Pasaporte…)
ClientAdditionalAccountID	int	Sí	Tipo organización (1=Persona jurídica, 2=Persona natural)
ClientRegistrationName	string	Sí	Razón social
ClientName	string	Sí	Nombre comercial
ClientEmail	string	Sí	Email del cliente
ClientObligations	List<string>	Sí	Obligaciones tributarias
ClientPartyTax	List<TaxScheme>	Sí	Impuestos del cliente
ClientCountrySubentityCode	string	Sí	Código departamento
ClientCityCode / CityName	string	Sí	Código y nombre ciudad
ClientAddressLine	string	Sí	Dirección
ClientCountryIdentificationCode	string	Sí	Código país (ej: CO)
PaymentID	string	Sí	Forma pago: 1=Contado, 2=Crédito
PaymentCode	string	Sí	Medio de pago DIAN
PaymentDate	DateTime?	Sí si crédito	Fecha vencimiento pago
TotalGross	decimal	Sí	Total bruto antes de impuestos
TotalTaxBase	decimal	Sí	Base gravable
TotalGrossPlusTaxes	decimal	Sí	Total bruto con impuestos
TotalPayableAmount	decimal	Sí	Total a pagar
TotalDiscounts	decimal?	No	Total descuentos
TaxTotals	List<TaxTotal>	Sí	Totales de impuestos
WithholdingTaxTotals	List<TaxTotal>	No	Retenciones
DocumentLines	List<DocumentLine>	Sí	Líneas del documento
AllowanceCharges	List<AllowanceCharge>	No	Cargos y descuentos globales
DocRefId / DocRefCufe	string	NC/ND	Referencia a documento origen (notas)
DocRefCreditNoteConcept	string	NC	Concepto de nota crédito
DocRefDebitNoteConcept	string	ND	Concepto de nota débito
BatchExternalId	string	No	ID de lote si es parte de envío masivo
SectorTypeCode	SectorType	No	Sector: 0=General, 1=Salud
SendAutomaticEmail	bool?	No	Forzar envío de email

Ejemplo mínimo

{
  "DocumentId": "FV-001",
  "Consecutive": 1,
  "InvoiceTypeCode": 1,
  "IssueDate": "2025-04-01T00:00:00",
  "DocumentCurrencyCode": "COP",
  "ResolutionNumber": 18760000001,
  "ResolutionPrefix": "FV",
  "ClientID": "900123456",
  "ClientIdentificationType": 31,
  "ClientDigitCheck": "7",
  "ClientAdditionalAccountID": 1,
  "ClientRegistrationName": "Empresa SAS",
  "ClientName": "Empresa SAS",
  "ClientEmail": "cliente@empresa.com",
  "ClientObligations": ["O-13"],
  "ClientPartyTax": [{ "ID": "ZZ", "Name": "No aplica" }],
  "ClientCountrySubentityCode": "11",
  "ClientCountrySubentity": "Bogotá D.C.",
  "ClientCityCode": "11001",
  "ClientCityName": "Bogotá",
  "ClientCountryIdentificationCode": "CO",
  "ClientCountryName": "Colombia",
  "ClientLanguage": "es",
  "ClientAddressLine": "Calle 100 # 10-20",
  "PaymentID": "1",
  "PaymentCode": "10",
  "TotalGross": 100000,
  "TotalTaxBase": 100000,
  "TotalGrossPlusTaxes": 119000,
  "TotalPayableAmount": 119000,
  "TaxTotals": [{ "TaxAmount": 19000, "TaxSubtotals": [{ "TaxAmount": 19000, "Percent": 19, "TaxableAmount": 100000, "TaxScheme": { "ID": "01", "Name": "IVA" } }] }],
  "DocumentLines": [{
    "LineExtensionAmount": 100000,
    "BaseQuantity": 1,
    "UnitCode": "EA",
    "Description": "Servicio profesional",
    "StandardItemIdentificationID": "SRV001",
    "StandardItemIdentificationCode": "999",
    "TaxTotals": [{ "TaxAmount": 19000, "TaxSubtotals": [{ "TaxAmount": 19000, "Percent": 19, "TaxableAmount": 100000, "TaxScheme": { "ID": "01", "Name": "IVA" } }] }]
  }]
}

Códigos

200Procesando (async)

400Request inválido

401No autorizado

GET /api/v1/Document/ValidateByCufe?cufe={cufe} API Key Header▶

Valida un documento por CUFE/CUDE. Usa autenticación por API Key en header (no Bearer token).

Autenticación especial: En lugar de JWT, enviar la API Key en el header configurado por ValidateDocument:ApiKeyHeaderAttribute. El endpoint es [AllowAnonymous] pero requiere este header.

Query param

Param	Tipo	Descripción
cufe	string	CUFE/CUDE/CUDS del documento a validar

Respuesta 200 — ValidateByCufeResponse

Campo	Tipo	Descripción
Cufe	string	CUFE del documento
IssueDate	DateTime	Fecha de emisión
Response	EventResponseBase	Respuesta de la DIAN
DocumentReference	EventDocReferenceBase	Referencia del documento
AccountingCustomer	EventParty	Datos del adquirente

Códigos

200OK

404No encontrado

401API Key inválida

📦

BatchController

Base: /api/v1/Batch

POST /api/v1/Batch User · Admin▶

Procesa un lote de documentos almacenados en storage externo. Dispara transformación masiva asíncrona.

Request — BatchUploadDocumentsRequest

Campo	Tipo	Req	Descripción
BatchExternalId	string	Sí	ID único del lote
ContainerName	string	Sí	Nombre del contenedor (empresa)
NumberOfFiles	int	Sí	Número de archivos en el lote

Respuesta 200

{ "GUID": "a1b2c3...", "Message": "Batch processing started" }

Códigos

200Iniciado

400Request inválido

500Error interno

POST /api/v1/Batch/ProcessPdfFiles User · Admin▶

Carga archivos PDF del directorio de lote al storage y genera representaciones gráficas.

Request — BatchUploadDocumentsRequest

Campo	Tipo	Descripción
BatchExternalId	string	ID del lote
ContainerName	string	Contenedor destino
NumberOfFiles	int	Cantidad de archivos PDF

Códigos

200OK

400Inválido

GET /api/v1/Batch/{BatchExternalId} User · Admin▶

Consulta el estado y detalle de un lote por su ID externo.

Path param

Param	Tipo
BatchExternalId	string

Códigos

200Detalle del lote

404No encontrado

⚙️

EventController

Base: /api/v1/Event

POST /api/v1/Event Payroll · Admin▼

Procesa un evento sobre un documento existente: acuse de recibo, aceptación, rechazo.

Request — EventRequest

Campo	Tipo	Req	Descripción
UUID	string	Sí	CUFE/CUDE/CUDS del documento
Action	int	Sí	30=Acuse recibo, 31=Rechazo, 32=Aceptación mercancía, 33=Aceptación expresa
EventId	string	Sí	ID único del evento en la empresa
IsTest	bool	No	Ambiente de pruebas
ActionName / ActionLastName	string	No	Nombre del responsable
ActionIdentificationType	int	No	Tipo ID responsable (11-42, 50, 91)
ActionIdentificationNumber	string	No	Número de ID
ActionTitle / ActionArea	string	No	Cargo y área del responsable
ClaimCode	int?	Sí si Action=31	Motivo rechazo: 1=Inconsistencias, 2=Entrega parcial mercancía, 3=Entrega parcial servicio, 4=Servicio no prestado

Ejemplo

{
  "UUID": "fe6e2bf4abc1234567890abcdef1234567890abc1234567890abc12345678901234",
  "Action": 30,
  "EventId": "EVT-001",
  "ActionName": "John",
  "ActionLastName": "Doe",
  "ActionIdentificationType": 13,
  "ActionIdentificationNumber": "12345678"
}

Códigos

200Procesado

400Request inválido

💼

PayrollController

Base: /api/v1/Payroll

POST /api/v1/Payroll Payroll · Admin▶

Procesa un documento de nómina electrónica. Genera CUNE y envía a la DIAN.

Request — PayrollRequest (campos principales)

Campo	Tipo	Req	Descripción
DocumentId	string	Sí	ID del documento
IssueDate	DateTime	Sí	Fecha de emisión
DocumentType	PayrollDocumentType	Sí	Tipo de nómina
IsTest	bool	No	Pruebas DIAN
PayrollPeriod	PeriodType	Sí	Período de pago
Prefix / Consecutive	string / long	Sí	Prefijo y consecutivo
CurrencyCode	string	Sí	Moneda (ej: COP)
NoveltyCUNE	string	No	CUNE si es novedad
PeriodIncomeSettlementDate	DateTime	Sí	Inicio período liquidación
PeriodEndSettlementDate	DateTime	Sí	Fin período liquidación
Employee	PayrollEmployee	Sí	Datos del empleado
Location	Location	Sí	Ubicación
PaymentMean	PaymentMeanType	Sí	Forma de pago
PaymentMethod	string	Sí	Método de pago
PaymentDate	DateTime	Sí	Fecha de pago
Accruals	List<Accrued>	Sí	Devengados
Deductions	List<Deduction>	Sí	Deducciones
TotalAccruedTotalAmount	decimal	Sí	Total devengado
TotalDeductionTotalAmount	decimal	Sí	Total deducido
TotalPayableAmount	decimal	Sí	Neto a pagar
PayrollReference	PayrollReference	No	Referencia a nómina anterior (novedades)

PayrollEmployee

Campo	Tipo	Descripción
Type / SubType	enum	Tipo y subtipo de empleado
IdentificationType	PayrollIdentificationType	Tipo de identificación
Identification	string	Número de documento
Surname / SecondSurname / Name	string	Apellidos y nombre
ContractStartDate	DateTime?	Fecha inicio contrato
IntegralSalary	bool	Salario integral
Salary	decimal	Salario base
ContractType	ContractTypeEnum	Tipo de contrato

Códigos

200Procesando

400Request inválido

GET /api/v1/Payroll/Trace/{TrackId} User · Admin▶

Consulta el estado de procesamiento de una nómina por TrackId.

Path param

Param	Tipo
TrackId	string

Códigos

200Estado del proceso

404No encontrado

🔍

TraceController

Base: /api/v1/Trace

GET /api/v1/Trace/{TrackId} User · Admin▶

Consulta el estado de procesamiento de un documento por TrackId (GUID generado en el proceso).

Path param

Param	Tipo
TrackId	string

Códigos

200Estado del proceso

404No encontrado

GET /api/v1/Trace/QueryByERPDocumentIdAsync/{DocumentId} User · Admin▶

Consulta el estado de procesamiento por el ID del documento en el ERP (DocumentId enviado originalmente).

Path param

Param	Tipo
DocumentId	string

Códigos

200Estado del proceso

404No encontrado

📎

LoadPdfController

Base: /api/v1/LoadPdf

POST /api/v1/LoadPdf User · Admin▶

Carga un PDF en base64 asociado a un documento existente y lo almacena en storage.

Request — LoadPdfRequest

Campo	Tipo	Req	Descripción
DocumentId	string	Sí	ID del documento ERP al que pertenece el PDF
Base64Content	string	Sí	Contenido del PDF codificado en Base64

Ejemplo

{ "DocumentId": "FV-001", "Base64Content": "JVBERi0xLjQK..." }

Códigos

200Cargado

400Inválido

404Documento no encontrado

📋

Modelos — Adapter

TaxScheme

Compartido

Campo	Tipo	Descripción
ID	string	01=IVA, 02=IC, 03=ICA, 04=INC, 05=ReteIVA, 06=ReteRenta, 07=ReteICA, 08=IC Porcentual, ZZ=No aplica
Name	string	Nombre del tributo

TaxTotal / TaxSubtotal

Compartido

Campo	Tipo	Descripción
TaxAmount	decimal	Valor total del impuesto
TaxSubtotals	List<TaxSubtotal>	Subtotales por tarifa
TaxSubtotal
TaxAmount	decimal	Valor del impuesto en este subtotal
TaxableAmount	decimal?	Base gravable
Percent	decimal?	Porcentaje (ej: 19)
TaxScheme	TaxScheme	Tributo aplicado
BaseUnitMeasure / BaseUnitMeasureCode	decimal? / string	Base por unidad (tributos unitarios)
PerUnitAmount	decimal?	Valor por unidad

DocumentLine

Request

Campo	Tipo	Req	Descripción
LineExtensionAmount	decimal	Sí	Total de la línea
BaseQuantity	decimal	Sí	Cantidad
UnitCode	string	Sí	Unidad de medida UNECE (EA, KGM, LTR…)
Description	string	Sí	Descripción del bien/servicio
StandardItemIdentificationID	string	Sí	Código del ítem en el ERP
StandardItemIdentificationCode	string	Sí	Estándar de codificación (999=interno, 001=EAN, etc.)
PriceAmount	decimal?	No	Precio unitario
TaxTotals	List<TaxTotal>	Sí	Impuestos de la línea
WithholdingTaxTotals	List<TaxTotal>	No	Retenciones de la línea
AllowanceCharges	List<AllowanceCharge>	No	Descuentos/cargos de la línea
BrandName / ModelName	string	No	Marca y modelo
Note	string	No	Nota adicional

AllowanceCharge

Request

Campo	Tipo	Req	Descripción
ChargeIndicator	bool	Sí	true=cargo, false=descuento
AllowanceChargeReason	string	Sí	Descripción del descuento/cargo
Amount	decimal	Sí	Valor
AllowanceType	AllowanceType	Sí	1=Valor fijo, 2=Porcentaje
MultiplierFactorNumeric	decimal	Si %	Porcentaje aplicado
BaseAmount	decimal	Si %	Base para calcular el porcentaje
AllowanceChargeReasonCode	AllowanceCode	No	Código de categoría de descuento

Documentación API

AuthenticationController

Modelos — Security

AuthenticateRequest

AuthenticateResponse

DocumentController v1

BatchController

EventController

PayrollController

TraceController

LoadPdfController

Modelos — Adapter

TaxScheme

TaxTotal / TaxSubtotal

DocumentLine

AllowanceCharge