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

Campos generales a nivel global de una nota crédito genérica

Header

Especificación y definición de datos del Header de la Nota Crédito, cuando el Adquiriente tiene los datos completos.

1. Logo (NC)

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 (NC)

Json (DTO)

{
  "SeriePrefix": "NC",
  "SerieNumber": "120",
  "CorrelationDocumentId": "POSTMAN-120",
  "SerieExternalKey": "5vjX+aBptT",
  "OperationType": "20"
}

UBL-XML

  <cbc:ID>NC120</cbc:ID>
  <cbc:ActualDeliveryDate>2023-11-27</cbc:ActualDeliveryDate>
  <cbc:CustomizationID>20</cbc:CustomizationID>

Observaciones

SeriePrefix: Prefijo definido por el emisor, maximo 4 caracteres.

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

SerieNumber: Número de documento: Número de la nota crédito.
Incluye prefijo + consecutivo de NC definido por el emisor.

• 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. Sin embargo, los tipos de operación para Nota crédito son:

• Tipo Operación 20, Nota Crédito obligatorio, referencia a facturas.

• Tipo Operación 22, Nota Crédito sin referencia a facturas.

Longitud

• 24 CARACTERES

3. Moneda (NC)

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

4 - 5. Forma de Pago (NC)

Json (DTO)

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

UBL-XML

  <cac:PaymentMeans>
  <cbc:ID>1</cbc:ID><!-- (4) -->
  <cbc:PaymentMeansCode>20</cbc:PaymentMeansCode><!-- (5) -->
  <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

• 4:25 CARACTERES

• 5:25 CARACTERES

6. Razón de Crédito (NC)

Json (DTO)

{
  ReasonCredit: "5"
}

UBL-XML

  <cac:DiscrepancyResponse>
  <cbc:ReferenceID>SETP990040002</cbc:ReferenceID>
  <cbc:ResponseCode>5</cbc:ResponseCode>
  <cbc:Description>Devolución de parte de los bienes; no aceptación de partes del servicio</cbc:Description>
  </cac:DiscrepancyResponse>

Observaciones

ReasonCredit: Los códigos de las causales de una nota crédito CreditNoteReasons están disponibles en el método del WEB API de Saphety: CreditNoteReasons

Longitud

• 80 CARACTERES

7. Fecha de Emisión (NC)

Json (DTO)

{
  "IssueDate": "2023-11-27T12:12:12", //(Formato para JSON: aaaa-mm-ddThh:mm:ss)
  "DueDate": 2"023-11-27T12:12:12",  
  "DeliveryDate": "2023-11-27T12:12:12"
}

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 NC aaaa-mm-ddThh:mm:ss.

• (IssueDate): Fecha de generación de la NC.
  Formato predeterminado: aaaa-mm-dd Fecha de emisión.
  

• (IssueTime): Fecha de generación de la NC.
  Formato predeterminado: hh:mm:ss
  Rechazo: La fecha de emisión debe ser igual a la fecha de firma de la NC.
  

DueDate: Fecha de pago.

• Formato predeterminado: aaaa-mm-ddThh:mm:ss.
  

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

8. Fecha Validación DIAN (NC)

Json (DTO)

NA

UBL-XML

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

Observaciones

Fecha Validación DIAN.

Longitud

25 CARACTERES

9. Tipo de Nota (NC)

Json (DTO)

Tipo de Nota

UBL-XML

  <cbc:CreditNoteTypeCode>91</cbc:CreditNoteTypeCode>

Observaciones

NA

Longitud

• 25 CARACTERES

Información del Emisor a nivel global de una Nota Crédito genérica.

10. Datos Emisor (NC)

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. Tipo de Contribuyente (NC)

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

12. Correo (NC)

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

13. Información Tributaria (NC)

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

14. Razón Social (NC)

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

• 45 CARACTERES

15. Dirección (NC)

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 (NC)

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 (NC)

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 Nota Crédito genérica.

18. Datos del Adquiriente (NC)

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 - 23. Razón Social y Tipo Contribuyente del Adquiriente (NC)

Json (DTO)

{
	// Si es de tipo LegalType = Legal 
	"CustomerParty": {
		"LegalType": "Legal", // (19)
		"Name": "Saphety Transacciones Electrónicas S.A.S" // (23)
	},
	
	// Si es de tipo natural LegalType= Natural 
	"CustomerParty": {
		"LegalType": "Natural", // (19)
		"Person": { // (23)
			"FirstName": "FirstName",
			"MiddleName": "MiddleName",
			"FamilyName": "FamilyName"
		}
	}
}

UBL-XML

  <!-- Si es de tipo LegalType = Legal -->
  <cac:AccountingCustomerParty>
  <cbc:AdditionalAccountID schemeAgencyID="195">1</cbc:AdditionalAccountID><!-- (19) -->
  <cac:Party><cac:PartyName>
  <cbc:Name>Saphety Transacciones Electrónicas S.A.S</cbc:Name><!-- (23) -->
  </cac:PartyName></cac:Party>
  </cac:AccountingCustomerParty>

  <!-- Si es de tipo Natural LegalType = Natural -->
  <cac:AccountingCustomerParty>
  <cbc:AdditionalAccountID schemeAgencyID="195">2</cbc:AdditionalAccountID><!-- (19) -->
  <cac:Party><cac:PartyName>
  <cbc:Name>FirstName MiddleName FamilyName</cbc:Name><!-- (23) -->
  </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

20. Impuesto Principal (NC)

Json (DTO)

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

UBL-XML

  <cac:AccountingCustomerParty>
  <cac:TaxScheme>
  <cbc:ID>ZZ</cbc:ID> <!-- (20) --> 
  <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 RepresentationTypes están disponibles en el método del WEB API de Saphety: RepresentationTypes.

Longitud

• 36 CARACTERES

21 - 22. Correo (NC)

Json (DTO)

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

UBL-XML

  <cac:AccountingCustomerParty>
  <cac:Party><cac:Contact>
  <cbc:Telefax>1234567</cbc:Telefax>
  <cbc:ElectronicMail>correo@sovos.com</cbc:ElectronicMail><!-- (21) -->
  </cac:Contact></cac:Party>
  </cac:AccountingCustomerParty>

Observaciones

Email: Correo electrónico del adquiriente.

Longitud

• 21: 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 Nota Crédito, 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 (NC)

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