Guía de Integración a Nivel Global (Header)#
Campos generales a nivel global de una factura de venta genérica#
Header#
El Header (encabezado) de la Factura Electrónica de Venta contiene la información general del documento, incluyendo los datos principales del emisor, del adquiriente y las condiciones generales de la transacción.
A continuación, se presenta la especificación y definición de los datos que conforman el encabezado de una factura de venta genérica, en el escenario en que el adquiriente proporciona la información completa.
1. Logo (FV)
El logo proviene del sistema y está preconfigurado en la plataforma SaphetyDoc.
Debe mostrarse en la parte superior izquierda del documento.
No aplica.
Tamaño en píxeles: 180px de ancho x 70px de alto.
2. Tipo de Documento (FV)
{
"SeriePrefix": "SETP",
"SerieNumber": "990053146",
"CorrelationDocumentId": "POSTMAN-990053146",
"SerieExternalKey": "/R8gksxDnZ",
"OperationType": "10"
}
<cbc:ID>SETP990053146</cbc:ID> <!-- Incluye prefijo + consecutivo de factura autorizados por la DIAN. -->
<cbc:ActualDeliveryDate>2023-11-27</cbc:ActualDeliveryDate>
<cbc:CustomizationID>10</cbc:CustomizationID>
SeriePrefix: Prefijo autorizado por el SIE de Numeración
*Rechazo:- No debe contener espacios ni guiones.
SerieNumber: Consecutivo autorizado.
Rechazo: No se permiten caracteres adicionales como espacios o guiones.
CorrelationDocumentId: ID único del sistema del emisor (máximo 36 caracteres)
SerieExternalKey: El campo SerieExternalKey se obtiene realizando la consulta por el método API o consultando en el portal administrativo de Saphety.
OperationType: Consulta los tipos de operación disponibles en: OperationType.
24 caracteres
3. Fecha de Emisión (FV)
{
"IssueDate": "2022-01-07T12:35:32",
"DeliveryDate": "2022-01-07T00:00:00"
}
<cbc:IssueDate>2023-11-27</cbc:IssueDate>
<cbc:IssueTime>12:12:12-05:00</cbc:IssueTime>
Fecha de emisión: Fecha de generación de la factura aaaa-mm-ddThh:mm:ss.
(IssueDate): Fecha de generación de la factura.
Formato predeterminado: aaaa-mm-dd Fecha de emisión.(IssueTime): Fecha de generación de la factura.
Formato predeterminado: hh:mm:ss
Rechazo: La fecha de emisión debe ser igual a la fecha de firma de la factura.
DeliveryDate: Fecha efectiva de entrega de los bienes y/o servicios.
Formato predeterminado: aaaa-mm-ddThh:mm:ss
Rechazo: Si ActualDeliveryDate < IssueDate.
25 caracteres
4. Moneda (FV)
{
"Currency": "COP"
}
<cbc:DocumentCurrencyCode>COP</cbc:DocumentCurrencyCode>
Currency: Código de moneda debe ser igual a COP
Rechazo: Si el valor de este elemento no corresponde a “COP”.
25 caracteres
5 - 6. Forma de Pago (FV)
{
"PaymentMeans": [
{
"Code": "20", //(6)
"Mean": "1", //(5)
"DueDate": "2023-11-27"
}
]
}
<cac:PaymentMeans>
<cbc:ID>1</cbc:ID><!-- (5) -->
<cbc:PaymentMeansCode>20</cbc:PaymentMeansCode><!-- (6) -->
<cbc:PaymentDueDate>2023-11-27</cbc:PaymentDueDate>
</cac:PaymentMeans>
Code: Código correspondiente al método de pago, el listado de los tipos de PaymentMeans están disponibles en el método del WEB API de Saphety: PaymentmeansCode.
Mean: Los códigos de las formas de pago paymentmeansmeans están disponibles en el método del WEB API de Saphety: PaymentMeansMeans.
DueDate: Fecha del plazo de la forma de pago cuando es crédito, Formato predeterminado: aaaa-mm-dd
25 caracteres (5)
80 caracteres (6)
7. Fecha Vencimiento (FV)
{
"DueDate": "2023-11-27T12:12:12"
}
<cbc:DueDate>2023-11-27</cbc:DueDate>
Fecha de vencimiento de la factura, Formato predeterminado: aaaa-mm-ddThh:mm:ss
25 caracteres
8. Fecha Validación DIAN (FV)
NA
Solo es visible en el xml firmado por DIAN (ApplitacionResponse).
Fecha Validación DIAN.
25 caracteres
9. Campos Personalizables Representación Gráfica (FV)
{
"GraphicalRepresentationCustomFields":
[
{
"Key": "plazo",
"Value": "30 días"
}
]
}
NA
Campos para informar el plazo en la Representación Gráfica
Key: Debe informar el texto “plazo”.
Value: Debe informar el plazo, ejemplo: “30 días”.
25 caracteres
Información del Emisor a nivel global de una factura de venta genérica.#
10. Datos Emisor (FV)
{
"IssuerParty": {
"Identification": {
"DocumentNumber": "900606963",
"DocumentType": "NIT",
"CountryCode": "CO",
"CheckDigit": "4"
}
}
}
<cac:AccountingSupplierParty>
<cac:Party>
<cac:PartyTaxScheme>
<cbc:CompanyID schemeID="4" schemeName="31" schemeAgencyID="195" schemeAgencyName="CO, DIAN (Dirección de Impuestos y Aduanas Nacionales)">900606963</cbc:CompanyID>
</cac:PartyTaxScheme>
</cac:Party>
</cac:AccountingSupplierParty>
DocumentNumber: NIT del emisor.
Rechazo: NIT no autorizado a facturar electrónicamente.
DocumentType: Tipos de documento, el listado de los tipos de identificación están disponibles en el método del WEB API de Saphety: identificationDocumentTypes.
CountryCode: Los códigos de los países countrycodes están disponibles en el método del WEB API de Saphety: CountryCode.
CheckDigit: Digito de Verificación del NIT del emisor.
36 caracteres
11. Razón Social (FV)
“Razón Social “FE DEMO” viene de sistema (Pre configurado en la plataforma SaphetyDoc.)”
<cac:AccountingSupplierParty>
<cac:Party>
<cac:PartyTaxScheme>
<cbc:RegistrationName>FE DEMO</cbc:RegistrationName>
</cac:PartyTaxScheme>
</cac:Party>
</cac:AccountingSupplierParty>
Texto libre.
36 caracteres
12. Tipo de Contribuyente (FV)
“Tipo de Contribuyente “Persona Jurídica” viene de sistema (Pre configurado en la plataforma SaphetyDoc.)”
<cac:AccountingCustomerParty>
<cbc:AdditionalAccountID schemeAgencyID="195">1</cbc:AdditionalAccountID>
</cac:AccountingCustomerParty>
Tipo de contribuyente: Los códigos del tipo de contribuyente están disponibles en el método del WEB API de Saphety: LegalTypes.
36 caracteres
13. Correo (FV)
“Correo “fedemo@saphety.com” viene de sistema (Pre configurado en la plataforma SaphetyDoc.)”
<cac:AccountingSupplierParty>
<cac:Party>
<cac:Contact>
<cbc:ElectronicMail>fedemo@saphety.com</cbc:ElectronicMail>
</cac:Contact>
</cac:Party>
</cac:AccountingSupplierParty>
Texto para indicar la dirección de correo electrónico.
36 caracteres
14. Información Tributaria (FV)
“Información Tributaria “Impuesto sobre las ventas – IVA” + “Gran contribuyente, Autorretenedor, Agente de retención en el impuesto sobre las ventas, Régimen Simple de Tributación – SIMPLE”, viene del sistema (Pre configurado en la plataforma SaphetyDoc).”
<cac:AccountingSupplierParty>
<cbc:TaxLevelCode listName="48">O-13,O-15,O-23,O-47</cbc:TaxLevelCode>
</cac:AccountingSupplierParty>
Régimen Fiscal: Debe corresponder a uno de los regímenes fiscales disponibles en el endpoint.
TaxScheme Responsabilidades fiscales:
O-13 Gran contribuyente.
O-15 Autorretenedor.
O-23 Agente de retención en el impuesto sobre las ventas.
O-47 Régimen Simple de Tributación – SIMPLE.
Los códigos de Régimen Fiscal están disponibles en el método del WEB API de Saphety: ResponsabilityTypes.
210 caracteres 2 líneas
15. Dirección (FV)
“Dirección “Calle 78 # 3-56” viene de sistema (Pre configurado en la plataforma SaphetyDoc.)”
<cac:PhysicalLocation>
<cac:Address>
<cac:AddressLine>
<cbc:Line>Calle 78 # 3-56</cbc:Line>
</cac:AddressLine>
</cac:Address>
</cac:PhysicalLocation>
Texto libre.
45 caracteres
16. Departamento (FV)
“Departamento “Bogotá” viene de sistema (Pre configurado en la plataforma SaphetyDoc.)”
<cac:PhysicalLocation>
<cac:Address>
<cbc:CountrySubentity>Bogotá</cbc:CountrySubentity>
</cac:Address>
</cac:PhysicalLocation>
Texto libre.
30 caracteres
17. Municipio (FV)
“Municipio “Bogotá D.c.” viene de sistema (Pre configurado en la plataforma SaphetyDoc.)
<cac:PhysicalLocation>
<cac:Address>
<cbc:CityName>Bogotá D.c</cbc:CityName>
</cac:Address>
</cac:PhysicalLocation>
Texto libre.
30 caracteres
Información del Adquiriente a nivel global de una factura de venta genérica para persona Jurídica o Natural.#
18. Datos del Adquiriente (FV)
{
// Si el Adquiriente es de tipo Legal
"CustomerParty": {
"Identification": {
"DocumentNumber": "900606963",
"DocumentType": "NIT",
"CountryCode": "CO",
"CheckDigit": "4"
}
},
//Si el Adquiriente es de tipo Natural
"CustomerParty": {
"Identification": {
"DocumentNumber": "123456789",
"DocumentType": "CitizenshipCard",
"CountryCode": "CO"
}
}
}
<!-- Si el Adquiriente es de tipo Legal -->
<cac:AccountingCustomerParty>
<cac:Party><cac:PartyTaxScheme>
<cbc:CompanyID schemeID="4" schemeName="31" schemeAgencyID="195" schemeAgencyName="CO, DIAN (Dirección de Impuestos y Aduanas Nacionales)">900606963</cbc:CompanyID>
<cac:Country>
<cbc:IdentificationCode>CO</cbc:IdentificationCode>
<cbc:Name languageID="es">Colombia</cbc:Name>
</cac:Country>
</cac:PartyTaxScheme></cac:Party>
</cac:AccountingCustomerParty>
<!-- Si el Adquiriente es de tipo Natural -->
<cac:AccountingCustomerParty>
<cac:Party><cac:PartyTaxScheme>
<cbc:CompanyID schemeName="13" schemeAgencyID="195" schemeAgencyName="CO, DIAN (Dirección de Impuestos y Aduanas Nacionales)">123456789</cbc:CompanyID>
<cac:Country>
<cbc:IdentificationCode>CO</cbc:IdentificationCode>
<cbc:Name languageID="es">Colombia</cbc:Name>
</cac:Country>
</cac:PartyTaxScheme></cac:Party>
</cac:AccountingCustomerParty>
DocumentNumber: Número de documento del adquiriente.
Rechazo:
NIT no autorizado a facturar electrónicamente
Nit o Documento de Identificación informado No corresponde al registrado en el RUT con respecto a la razón social o nombre comercial suministrado.
DocumentType: Tipo de documento, el listado de los tipos de DocumentType están disponibles en el método del WEB API de Saphety: DocumentType.
CheckDigit: DV del NIT del Adquiriente.
CountryCode: Código identificador del país, el listado de los tipos de CountryCode están disponibles en el método del WEB API de Saphety: CountryCode.
36 caracteres
19 - 20. Razón Social y Tipo Contribuyente del Adquiriente (FV)
{
// Si es de tipo LegalType = Legal
"CustomerParty": {
"LegalType": "Legal", // (20)
"Name": "Saphety Transacciones Electrónicas S.A.S" // (19)
},
// Si es de tipo natural LegalType= Natural
"CustomerParty": {
"LegalType": "Natural", // (20)
"Person": { // (19)
"FirstName": "FirstName",
"MiddleName": "MiddleName",
"FamilyName": "FamilyName"
}
}
}
<!-- Si es de tipo LegalType = Legal -->
<cac:AccountingCustomerParty>
<cbc:AdditionalAccountID schemeAgencyID="195">1</cbc:AdditionalAccountID><!-- (20) -->
<cac:Party><cac:PartyName>
<cbc:Name>Saphety Transacciones Electrónicas S.A.S</cbc:Name><!-- (19) -->
</cac:PartyName></cac:Party>
</cac:AccountingCustomerParty>
<!-- Si es de tipo Natural LegalType = Natural -->
<cac:AccountingCustomerParty>
<cbc:AdditionalAccountID schemeAgencyID="195">2</cbc:AdditionalAccountID><!-- (20) -->
<cac:Party><cac:PartyName>
<cbc:Name>FirstName MiddleName FamilyName</cbc:Name><!-- (19) -->
</cac:PartyName></cac:Party>
</cac:AccountingCustomerParty>
LegalType: Los tipos de personas legales LegalTypes están disponibles en el método del WEB API de Saphety: LegalTypes
Name: Nombre o razón social del adquiriente que está registrado en el RUT.
45 caracteres
21. Impuesto Principal (FV)
{
"CustomerParty": {
"TaxScheme": "ZZ" //(21)
"ResponsabilityTypes":["R-99-PN"]
}
}
<cac:AccountingCustomerParty>
<cac:TaxScheme>
<cbc:ID>ZZ</cbc:ID> <!-- (21) -->
<cbc:Name>No Aplica</cbc:Name>
</cac:TaxScheme>
</cac:AccountingCustomerParty>
TaxScheme: Identificador del Régimen Fiscal del adquirente, el listado de los tipos de TaxScheme están disponibles en el método del WEB API de Saphety: TaxScheme.
ResponsabilityTypes: Los códigos de las responsabilidades ResponsabilityTypes están disponibles en el método del WEB API de Saphety: ResponsabilityTypes.
36 caracteres
22. Correo (FV)
{
"CustomerParty": {
"TeleFax": "1234567",
"Email": “correo@sovos.com” //(22)
}
}
<cac:AccountingCustomerParty>
<cac:Party><cac:Contact>
<cbc:Telefax>1234567</cbc:Telefax>
<cbc:ElectronicMail>correo@sovos.com</cbc:ElectronicMail><!-- (22) -->
</cac:Contact></cac:Party>
</cac:AccountingCustomerParty>
Email: Correo electrónico del adquiriente.
22: 36 caracteres
24 - 25 - 26. Datos Ubicación (FV)
{
"CustomerParty": {
"Address": {
"DepartmentCode": "11", //(25)
"CityCode": "11001", //(26)
"AddressLine": " Calle 97a No. 9 - 45", //(24)
"PostalCode": "110221",
"Country": "CO"
}
}
}
<cac:AccountingCustomerParty>
<cac:Party><cac:PhysicalLocation>
<cac:Address>
<cbc:ID>11001</cbc:ID> <!-- (26) -->
<cbc:CityName>Bogota D.C.</cbc:CityName> <!-- (26) -->
<cbc:PostalZone>110221</cbc:PostalZone> <!-- (25) -->
<cbc:CountrySubentity>Bogotá</cbc:CountrySubentity>
<cbc:CountrySubentityCode>11</cbc:CountrySubentityCode> <!-- (25) -->
<cac:AddressLine>
<cbc:Line>Calle 97a No. 9 - 45</cbc:Line> <!-- (24) -->
</cac:AddressLine>
<cac:Country>
<cbc:IdentificationCode>CO</cbc:IdentificationCode>
<cbc:Name languageID="es">Colombia</cbc:Name>
</cac:Country>
</cac:Address>
</cac:PhysicalLocation></cac:Party>
</cac:AccountingCustomerParty>
DepartmentCode: Los códigos de los departamentos DepartmentCode están disponibles en el método del WEB API de Saphety: DeparmentCode.
CityCode: Los códigos de los países CityCode están disponibles en el método del WEB API de Saphety: CityCode.
AddressLine: Elemento de texto libre, que el emisor puede utilizar para poner toda la información de la dirección del adquirente, en lugar de utilizar elementos estructurados.
PostalCode: Los códigos postales PostalCode están disponibles en el método del WEB API de Saphety: PostalCode.
Country: Los códigos de los paises CountryCodes están disponibles en el método del WEB API de Saphety: CountryCode.
Important
Debe tener encuentra que los códigos de DepartmentCode, CityCode y PostalCode deben cumplir con la referencia geográfica, es decir no se permite informar códigos postales o códigos de ciudades que no correspondan con el departamento.
24: 45 caracteres
25: 45 caracteres
26: 45 caracteres
Header Consumidor Final#
Esta sección describe la estructura y definición de los datos que conforman el encabezado (Header) de una Factura de Venta, en el caso en que el adquiriente no dispone de información completa o cuando la operación corresponde a un consumidor final.
En este escenario, algunos campos del adquiriente se completan con información genérica o valores predefinidos, de acuerdo con las disposiciones establecidas por la DIAN y las buenas prácticas de interoperabilidad electrónica.
Note
Este caso aplica cuando el adquiriente no proporciona la información completa, como el nombre o la identificación tributaria. En estos casos, se debe remitir a la DIAN la información estandarizada correspondiente, conforme a los lineamientos establecidos para operaciones con consumidor final.
1. Consumidor Final (FV)
{
"CustomerParty": {
"IsFinalConsumer": true
}
}
<cac:AccountingCustomerParty>
<cac:Party><cac:PartyTaxScheme>
<cbc:RegistrationName>Consumidor Final</cbc:RegistrationName>
<cbc:CompanyID schemeName="13">2222222222</cbc:CompanyID>
</cac:PartyTaxScheme></cac:Party>
</cac:AccountingCustomerParty>
IsFinalConsumer: Debe indicarse el texto “True” cuando se trate de un consumidor final.
Para la identificación del adquirente consumidor final, se debe utilizar el documento “222222222222”. Además, para informar que se trata del consumidor final del bien o servicio, se debe indicar el texto “consumidor final”.
Nit: 22 caracteres
Razón Social: 45 caracteres
Dirección: 45 caracteres