Guía de Integración a Nivel Global (Header)

Campos generales a nivel global de una factura de venta genérica

Header

Especificación y definición de datos del Header de la factura de venta, cuando el Adquiriente tiene los datos completos.

1. Logo (FV)

Json (DTO)

Logo viene del sistema (Pre configurado en la plataforma SaphetyDoc.).

UBL-XML

Se debe visualizar en la parte superior izquierda.

Observaciones

NA

Longitud

Tamaño en pixeles Horizontal: 180px Vertical: 70 px.

2. Tipo de Documento (FV)

Json (DTO)

{
  "SeriePrefix": "SETP",
  "SerieNumber": "990053146",
  "CorrelationDocumentId": "POSTMAN-990053146",
  "SerieExternalKey": "/R8gksxDnZ",
  "OperationType": "10"
}

UBL-XML

    <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>

Observaciones

SeriePrefix: Prefijo de la autorización de numeración de facturación dado por el SIE de Numeración.

• *Rechazo:- No se permiten caracteres adicionales como espacios o guiones.
  

SerieNumber: Número/Consecutivo de factura o factura cambiaria.

• Rechazo: No se permiten caracteres adicionales como espacios o guiones.
  

CorrelationDocumentId: Es un identificador único del sistema de generación del emisor y debe tener un máximo de 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: El listado de los diferentes tipos de operación están disponibles en el método del WEB API de Saphety: OperationType.

Longitud

24 CARACTERES

3. Fecha de Emisión (FV)

Json (DTO)

{
  "IssueDate": "2022-01-07T12:35:32",
  "DeliveryDate": "2022-01-07T00:00:00"
}

UBL-XML

  <cbc:IssueDate>2023-11-27</cbc:IssueDate>
  <cbc:IssueTime>12:12:12-05:00</cbc:IssueTime>

Observaciones

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.
  

Longitud

25 CARACTERES

4. Moneda (FV)

Json (DTO)

{
  "Currency": "COP"
}

UBL-XML

  <cbc:DocumentCurrencyCode>COP</cbc:DocumentCurrencyCode>

Observaciones

Currency: Código de moneda debe ser igual a COP
Rechazo: Si el valor de este elemento no corresponde a “COP”.

Longitud

25 CARACTERES

5 - 6. Forma de Pago (FV)

Json (DTO)

{
  "PaymentMeans": [
    { 
      "Code": "20", //(6)
      "Mean": "1", //(5)
      "DueDate": "2023-11-27" 
    }
  ]
}

UBL-XML

  <cac:PaymentMeans>
  <cbc:ID>1</cbc:ID><!-- (5) -->
  <cbc:PaymentMeansCode>20</cbc:PaymentMeansCode><!-- (6) -->
  <cbc:PaymentDueDate>2023-11-27</cbc:PaymentDueDate>
  </cac:PaymentMeans>

Observaciones

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

Longitud

• 25 CARACTERES (5)

• 80 CARACTERES (6)

7. Fecha Vencimiento (FV)

Json (DTO)

{
  "DueDate": "2023-11-27T12:12:12"
}

UBL-XML

  <cbc:DueDate>2023-11-27</cbc:DueDate>

Observaciones

Fecha de vencimiento de la factura, Formato predeterminado: aaaa-mm-ddThh:mm:ss

Longitud

25 CARACTERES

8. Fecha Validación DIAN (FV)

Json (DTO)

NA

UBL-XML

Solo es visible en el xml firmado por DIAN (ApplitacionResponse).

Observaciones

Fecha Validación DIAN.

Longitud

25 CARACTERES

9. Campos Personalizables Representación Gráfica (FV)

Json (DTO)

{
  "GraphicalRepresentationCustomFields": 
  [
    { 
      "Key": "plazo", 
      "Value": "30 días" 
    }
  ]
}

UBL-XML

NA

Observaciones

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”.

Longitud

25 CARACTERES

Información del Emisor a nivel global de una factura de venta genérica.

10. Datos Emisor (FV)

Json (DTO)

{
    "IssuerParty": { 
    "Identification": { 
      "DocumentNumber": "900606963", 
      "DocumentType": "NIT", 
      "CountryCode": "CO",
      "CheckDigit": "4"
       } 
    }
}

UBL-XML

  <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>

Observaciones

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.

Longitud

36 CARACTERES

11. Razón Social (FV)

Json (DTO)

“Razón Social “FE DEMO” viene de sistema (Pre configurado en la plataforma SaphetyDoc.)”

UBL-XML

  <cac:AccountingSupplierParty>
  <cac:Party>
  <cac:PartyTaxScheme>
  <cbc:RegistrationName>FE DEMO</cbc:RegistrationName>
  </cac:PartyTaxScheme>
  </cac:Party>
  </cac:AccountingSupplierParty>

Observaciones

Texto libre.

Longitud

36 CARACTERES

12. Tipo de Contribuyente (FV)

Json (DTO)

“Tipo de Contribuyente “Persona Jurídica” viene de sistema (Pre configurado en la plataforma SaphetyDoc.)”

UBL-XML

  <cac:AccountingCustomerParty>
  <cbc:AdditionalAccountID schemeAgencyID="195">1</cbc:AdditionalAccountID>
  </cac:AccountingCustomerParty>

Observaciones

Tipo de contribuyente: Los códigos del tipo de contribuyente están disponibles en el método del WEB API de Saphety: LegalTypes.

Longitud

36 CARACTERES

13. Correo (FV)

Json (DTO)

“Correo “fedemo@saphety.com” viene de sistema (Pre configurado en la plataforma SaphetyDoc.)”

UBL-XML

  <cac:AccountingSupplierParty>
  <cac:Party>
  <cac:Contact>
  <cbc:ElectronicMail>fedemo@saphety.com</cbc:ElectronicMail>
  </cac:Contact>
  </cac:Party>
  </cac:AccountingSupplierParty>

Observaciones

Texto para indicar la dirección de correo electrónico.

Longitud

36 CARACTERES

14. Información Tributaria (FV)

Json (DTO)

“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).”

UBL-XML

  <cac:AccountingSupplierParty>
  <cbc:TaxLevelCode listName="48">O-13,O-15,O-23,O-47</cbc:TaxLevelCode>
  </cac:AccountingSupplierParty>

Observaciones

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.
  

Longitud

210 caracteres 2 líneas

15. Dirección (FV)

Json (DTO)

“Dirección “Calle 78 # 3-56” viene de sistema (Pre configurado en la plataforma SaphetyDoc.)”

UBL-XML

 <cac:PhysicalLocation>
 <cac:Address>
 <cac:AddressLine>
 <cbc:Line>Calle 78 # 3-56</cbc:Line>
 </cac:AddressLine>
 </cac:Address>
 </cac:PhysicalLocation>

Observaciones

Texto libre.

Longitud

45 CARACTERES

16. Departamento (FV)

Json (DTO)

“Departamento “Bogotá” viene de sistema (Pre configurado en la plataforma SaphetyDoc.)”

UBL-XML

  <cac:PhysicalLocation>
  <cac:Address>
  <cbc:CountrySubentity>Bogotá</cbc:CountrySubentity>
  </cac:Address>
  </cac:PhysicalLocation>

Observaciones

Texto libre.

Longitud

30 CARACTERES

17. Municipio (FV)

Json (DTO)

“Municipio “Bogotá D.c.” viene de sistema (Pre configurado en la plataforma SaphetyDoc.)

UBL-XML

  <cac:PhysicalLocation>
  <cac:Address>
  <cbc:CityName>Bogotá D.c</cbc:CityName>
  </cac:Address>
  </cac:PhysicalLocation>

Observaciones

Texto libre.

Longitud

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)

Json (DTO)

{
   // 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"
		}
	}
}

UBL-XML

  <!-- 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>

Observaciones

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.

Longitud

36 CARACTERES

19 - 20. Razón Social y Tipo Contribuyente del Adquiriente (FV)

Json (DTO)

{
	// 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"
		}
	}
}

UBL-XML

  <!-- 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>

Observaciones

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.

Longitud

45 CARACTERES

21. Impuesto Principal (FV)

Json (DTO)

{
  "CustomerParty": { 
    "TaxScheme": "ZZ" //(21) 
    "ResponsabilityTypes":["R-99-PN"] 
  }
}

UBL-XML

  <cac:AccountingCustomerParty>
  <cac:TaxScheme>
  <cbc:ID>ZZ</cbc:ID> <!-- (21) --> 
  <cbc:Name>No Aplica</cbc:Name>
  </cac:TaxScheme>
  </cac:AccountingCustomerParty>

Observaciones

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.

Longitud

36 CARACTERES

22. Correo (FV)

Json (DTO)

{
  "CustomerParty": { 
    "TeleFax": "1234567", 
    "Email": “correo@sovos.com” //(22) 
  }
}

UBL-XML

  <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>

Observaciones

Email: Correo electrónico del adquiriente.

Longitud

22: 36 CARACTERES

24 - 25 - 26. Datos Ubicación (FV)

Json (DTO)

{
  "CustomerParty": { 
    "Address": { 
      "DepartmentCode": "11", //(25)
      "CityCode": "11001", //(26)  
      "AddressLine": " Calle 97a No. 9 - 45", //(24) 
      "PostalCode": "110221", 
      "Country": "CO" 
    } 
  }
}

UBL-XML

  <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>

Observaciones

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.

Longitud

• 24: 45 CARACTERES

• 25: 45 CARACTERES

• 26: 45 CARACTERES

Header Consumidor Final

Especificación y definición de datos del Header de la factura de venta, cuando el Adquiriente NO tiene los datos completos.

Note

Este caso es usado cuando el adquiriente no facilita datos como el nombre e identificación y se envía a la DIAN la información estandarizada.

1. Consumidor Final (FV)

Json (DTO)

{
  "CustomerParty": { 
    "IsFinalConsumer": true 
  }
}

UBL-XML

  <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>

Observaciones

IsFinalConsumer: Se debe informar el texto “True” cuando se trate de informar al consumidor final.
Identificación del adquirente, Para identificar al consumidor final, se utiliza el siguiente documento “222222222222” Para informar al consumidor final del bien o servicio se debe indicar el siguiente texto “consumidor final”

Longitud

• Nit: 22 CARACTERES

• Razón Social: 45 CARACTERES

• Dirección: 45 CARACTERES