Guía Técnica Para Consumo Api Factura Electrónica


Clarisa pone a su disposición una avanzada API que posibilita la integración fluida de su sistema, permitiéndole realizar diversas operaciones

Nuestro servicio incluye un riguroso proceso de verificación y validación de sus facturas, asegurando su aceptación y la correcta presentación de informes ante la  DIAN .

Estamos comprometidos en brindarle una experiencia eficiente y segura en la gestión de sus documentos financieros.

 

Antes de continuar:


Recuerde que para utilizar cualquier servicio de la API, es imprescindible contar con un token de autorización. Si no está seguro de cómo obtenerlo, recomendamos consultar la siguiente documentación para obtener instrucciones detalladas:
https://ayuda.clarisa.co/guia-para-consumir-api-de-login/

Importante !

Para el envío masivo de Facturas electrónicos, es decir mas de una factura, se debe enviar cada petición con intervalo de 3 segundos como mínimo para evitar el cruce de peticiones.

Crear Factura Electrónica

CABECERAVALOR
Content-Type application/json
Authorizationtoken de usuario

METODO : "POST"

NOTA: El ejemplo anterior corresponde a un petición con los datos mínimos

 

Propiedades Adicionales

Agregar múltiples impuestos

Nota Adicional

Es posible añadir múltiples impuestos a un ítem. Sin embargo, es importante tener en cuenta que no se pueden asignar dos impuestos del mismo tipo al mismo ítem. Por ejemplo, no es válido aplicar dos impuestos de tipo IVA sobre el mismo ítem.

tarifaTributo: esta se aplica según ley
factor: este representa la cantidad por la cual se aplica la tarifa en este caso representa 2500 ml de ítem por unidad

Agregar descuento a un ítem

Nota Adicional

Todos los descuentos aplicados a un ítem afectan a las bases imponibles.

Agregar descuento general al total de la Factura Electrónica

Nota Adicional

Para la factura electrónica, es posible aplicar tanto descuentos como recargos generales sin afectar las bases imponibles del documento.

Ejemplo de cálculos

A continuación, encontrarás un archivo Excel que sirve como ejemplo para ilustrar la manera en que se realizan los cálculos de la factura electrónica en diversos escenarios.

Además, puedes visualizar el JSON correspondiente a estos escenarios seleccionando la opción 'Ver JSON'.


 

Documentación adicional


Nombre Formato Oc Tamaño Descripción
NIT Alfanumérico 1..1 3-13 NIT de la empresa sin dígito de verificación
numeroResolucion numérico 1..1 14 Número de resolucion aprobada en la DIAN
prefijoDcto Alfanumérico 0..1 0-4 Prefijo asociado a la numeración
consecutivoDcto Numérico 1..1 1-9 Número del consecutivo asociado a la factura
fechaVencimiento String 1..1 10 Fecha de vencimiento del documento electrónico(Formato: yyyy-MM-dd)
mediosPago Array [] 1..N 3 Códigos de la DIAN de los medios de pago con los que se pagó el documento electrónico, dichos códigos van separados por coma. revisar tabla valores para medios de pago
formaPago String 1..1 1 Código de la DIAN asociado a la forma de pago del documento electrónico. revisar tabla valores para forma de Pago
extensiones 1..1 Datos donde se desceriben los beneficos del comprador y del punto de venta
dianExtension.beneficiosComprador 1..1 1 Información correspondiente a los beneficios del Comprador
beneficiosComprador.codigo String 1..1 50 Valor de la característica que se quiere informar (Código del comprador)
beneficiosComprador.nombreApellido String 1..1 100 Valor de la característica que se quiere informar (Nombres y apellidos del comprador)
beneficiosComprador.puntos String 1..1 50 Valor de la característica que se quiere informar (Cantidad de Puntos acumulados por el comprador)
dianExtension.puntoVenta 1..1 1 Datos donde se desceriben al punto de venta
puntoVenta.placaCaja String 1..1 50 Valor de la característica que se quiere informar (Placa de inventario de la Caja)
puntoVenta.ubicacionCaja String 1..1 50 Valor de la característica que se quiere informar (Ubicación de la caja ALMACEN)
puntoVenta.cajero String 1..1 100 Valor de la característica que se quiere informar (nombres y apellidos del cajero o vendedor)
puntoVenta.tipoCaja String 1..1 100 Valor de la característica que se quiere informar (Tipo de Caja)
puntoVenta.codigoVenta String 1..1 50 Valor de la característica que se quiere informar (Código de la Venta)
puntoVenta.subTotal String 1..1 50 Valor de la característica que se quiere informar (Subtotal de la venta)
cliente 1..1 Datos del Cliente del documento electrónico
cliente.nombreRazonSocial Alfanumérico 1..1 5-255 Cliente: Razón social o Nombre
cliente.tipoIdentificacion Alfanumérico 1..1 2 Código del tipo de identificación, véase la lista tipo de identificación.
cliente.numIdentificacion númerico 1..1 3-13 Número de identificación de cliente, sin dígito de verificación.
cliente.naturaleza String 1..1 7-8 Código de la naturaleza del cliente, véase valores para Naturaleza
cliente.direccion Alfanumérico 0..1 0-100 Dirección Cliente
cliente.ciudad String 0..1 5 Código DANE de la ciudad. La ciudad del cliente, véase la tabla valores para ciudad
cliente.telefono numérico 0..1 0-15 Télefono del cliente
cliente.email Alfanumérico 0..1 0-100 correo Electrónico
cliente.responsabilidadesFiscales Alfanumérico 1..1 3 Código de responsabilidades fiscales, véase tabla Responsabilidades fiscales cliente
cliente.respTributarias Alfanumérico 1..1 3 Código de responsabilidades tributarias, véase tabla Valores para Responsabilidades tributarias cliente
Observación String 0..1 0-1000 Texto libre para incluir una observacion en el documento
total numérico 1..1 0-15 Dec 0-6 Valor total del documento electrónico.
ítems Array [] 1..N Items asociados a la factura.
items.nombreItemVenta Alfanumérico 1..1 4-1000 Nombre del producto vendido
items.precioBaseUnitario numérico 1..1 0-15 Dec 0-6 Precio base por unidad del item
items.esRegalo Boleano 0..1 true o false Indiador si el el item facturado es un regalo, si su valor es true, se de debe agregarel precio de referencia
items.cantidad numérico 1..1 1-9 Cantidad vendida del ítem
items.código Alfanumérico 1..1 15 Código del producto vendido.
items.unidad Alfanumérico 1..1 4 código de la DIAN de la Unidad del producto. REVISAR tabla Valores para unidad
items.valorDescuento numérico 0..1 0-15 Dec 0-6 Valor de descuento aplicado al precio base del item por unidad
items.observacion Alfanumérico 1..1 0-1000 Observación del ítem
items.impuestos Array [] 1..N Lista de impuestos asociados
items.impuestos.tipo String 1..1 5 Tipo de impuesto aplicado al item, Valores para tipo impuestos
items.impuestos.claseImpuesto String 1..1 2 Clase de impuesto porcentual o nominal Valores para clase impuestos
items.impuestos.tarifaTributo númerico 1..1 4 Valor del impuesto fijado segun normativa
items.impuestos.factor númerico 0..1 0-15 Dec 0-2 Atribo que solo aplica a impuesto que requieren un calculo especial
listaDescuentosCargos Array [] 0..N Descuento o recargos asociados a la factura
listaDescuentosCargos.tipo String 1..1 10 Indicardor si pertertenece aun descuento o aun cargo Valores Descuento o Cargo
listaDescuentosCargos.codigo String 1..1 2 Indicardor de la condicion del descuento o cargo Valores el código del Descuento o Cargo
listaDescuentosCargos.valor númerico 1..1 0-15 Dec 0-2 Valor que afecta al total del documento segun sea descuento o cargo
listaDescuentosCargos.observacion String 0..1 0-1000 Texto libre para indicar uan observacion al descuento o cargo

Nombre Codigo
cedula de ciudadania CC
NIT NI
tarjeta de identidad TI
Pasaporte PA
Tarjeta de extranjeria TE
Cedula de extranjeria CE
Registro civil de nacimiento RC
Nit de otro país NO
NUIP NU
Carné diplomatico CD
Salvonconducto SC
Permiso Especial de permanencia PE
Certificado de nacido vivo CN
Adulto sin identificar AS
Menor sin identificar MS
Documento extranjero DE
Sin identificación SI
Documento de identificación extranjero DE
PEP PE


Nombre código
Acuerdo mutuo ZZZ
Efectivo 10
Consiganción bancaria 42
Tarjeta crédito 30
Tarjeta Débito 49
Bonos 71
Bookentry Crédito 15
Bookentry Débito 16
Cheque 20
Cheque bancario 23
Cheque certificado 25
Cheque Local 26
Cheque local transferible 92
Clearing entre partners 97
Clearing Nacional o Regional 9
Concentración de la demanda en efectivo / Desembolso (CCD) débito 18
Concentración de la demanda en efectivo /Desembolso Crédito (CCD) 17
Concentración Efectivo / Desembolso Crédito plus (CCD+) 32
Concentración efectivo / Desembolso Débito plus (CCD+) 43
Concentración Efectivo / Desembolso Débito plus (CCD+) 33
Concentración efectivo ahorros / Desembolso Crédito (CCD) 35
Concentración efectivo ahorros / Desembolso Drédito (CCD) 36
Concentración efectivo/Desembolso Crédito plus (CCD+) 41
Crédito ACH 2
Crédito Ahorro 13
Crédito de demanda ACH 6
Crédito Negocio Intercambio Corporativo (CTX) 28
Crédito Negocio Intercambio Corporativo (CTX) 39
Crédito Pago negocio corporativo (CTP) 19
Débito ACH 3
Débito Ahorro 14
Débito de demanda ACH 7
Débito Negocio Intercambio Corporativo (CTX) 40
Débito Negocio Intercambio Corporativo (CTX) 29
Débito Pago Negocio Corporativo (CTP) 27
Giro formato abierto 95
Giro referenciado 93
Giro urgente 94
Instrumento no definido 1
Mantener 8
Método de pago solicitado no usuado 96
Nota bancaria transferible 91
Nota cambiaria 44
Nota cambiaria esperando aceptación 24
Nota promisoria 60
Nota promisoria firmada 66
Nota promisoria firmada por el acreedor 61
Nota promisoria firmada por el acreedor, avalada por el banco 62
Nota promisoria firmada por el acreedor, avalada por un tercero 63
Nota promisoria firmada por el banco 64
Nota promisoria firmada por un banco avalada por otro banco 65
Nota promisoria firmada por un tercero avalada por un banco 67
Pago comercial urgente 52
Pago Negocio Corporativo Ahorros Crédito (CTP) 37
Pago Negocio Corporativo Ahorros Débito (CTP) 38
Pago Tesorería Urgente 53
Pago y depósito pre acordado (PPD) 34
Postgiro 50
Poyecto bancario 21
Proyecto bancario certificado 22
Retiro de nota por el acreedor 70
Retiro de nota por el acreedor sobre un banco 74
Retiro de nota por el acreedor, avalada por otro banco 75
Retiro de nota por el acreedor, sobre un banco avalada por un tercero 76
Retiro de una nota por el acreedor sobre un tercero 77
Retiro de una nota por el acreedor sobre un tercero avalada por un banco 78
Reversión Crédito Ahorro 11
Reversión crédito de demanda ACH 5
Reversión Débito Ahorro 12
Reversión débito de demanda ACH 4
Tarjeta Crédito 48
Tarjeta débito 31
Telex estándar bancario francés 51
Transferencia Crédito Bancario 45
Transferencia Débito Bancaria 47
Transferencia Débito Interbancario 46
Vales 72

Nombre Código
Contado 1
Crédito 2

Nombre Código
cedula de ciudadania CC
NIT NI
tarjeta de identidad TI
Pasaporte PA
Tarjeta de extranjeria TE
Cedula de extranjeria CE
Registro civil de nacimiento RC
Nit de otro país NO
NUIP NU
Carné diplomatico CD
Salvonconducto SC
Permiso Especial de permanencia PE
Certificado de nacido vivo CN
Adulto sin identificar AS
Menor sin identificar MS
Documento extranjero DE
Sin identificación SI
Documento de identificación extranjero DE
PEP PE

Descripción código
Persona natural NATURAL
Persona Jurídica JURIDICA

Si el cliente presenta varias responsabilidades fiscales, sus códigos deben ir separados por coma

Nombre Código
Gran contribuyente GRC
Autorretenedor ART
Agente de retención en el impuesto sobre las ventas RIV
Régimen de tributación- SIMPLE RST
No aplica – Otros NOA

Nombre Código
Impuesto al valor agregado IVA
Impuesto Nacional al Consumo INC
IVA + INC IEC
No aplica (ZZ) NOA

Nombre del campo Código
Unidad 94
Pieza 94
Centímetro CMT
Metro MTR
Pulgada INH
Centímetro cuadrado CMK
Metro cuadrado (m2) MTK
Pulgada cuadrada INK
Mililitro MLT
Litro LTR
Galón A76
Gramo GGR
Kilogramo KGM
Tonelada 54
Libra LBR
Servicio 94
Centímetro Cúbico (cm3) CMQ
Metro Cúbico MTQ

Descripción Código
Impuesto sobre la Ventas IVA
Impuesto al Consumo Departamental Nominal ICDN
Impuesto de Industria, Comercio y Aviso ICA
Impuesto Nacional al Consumo INC
Retención sobre el IVA RIVA
Retención sobre Renta RRENT
Retención sobre el ICA RICA
Impuesto al Consumo Departamental Porcentual ICPD
Cuota de Fomento Hortifrutícula FHCUL
Impuesto de Timbre TIM
Impuesto Nacional al Consumo de Bolsa Plástica INCB
Impuesto Nacional del Carbono INCAR
Impuesto Nacional a los Combustibles INCOM
Sobretasa a los combustibles STC
Contribución minoristas (Combustibles) SDCOM
Impuesto al Consumo de Datos ICDA
Impuesto al Consumo de Licores ICL
Impuesto nacional productos plásticos INPP
Impuesto a las bebidas ultraprocesadas azucaradas IBUA
Impuesto a los productos comestibles ultraprocesados industrialmente y/o con alto contenido de azúcares añadidos, sodio o grasas saturadas ICUI
AD VALOREM ADV
Otros tributos, tasas, contribuciones, y similares ZZ

Nota: Para el impuesto Exento se debe enviar:

tipo EXE
claseImpuesto PO
tarifaTributo 0

Para cuando el ítem es Excluido se debe enviar:

tipo EXC
claseImpuesto PO
tarifaTributo 0

Descripción Código
Impuesto de tipo nominal NM
Impuesto de tipo porcentual PO

Nombre Código
No condicionado 00
Condicionado 01

Nota:

Puede descargar el siguiente archivo de excel con las ciudades de Colombia 

 

Correcto

En caso de que la petición se ejecute sin errores se devolverá la siguiente respuesta:

CÓDIGO HTTP: 200

 

Error

Si la solicitud no es correcta, puede recibir respuesta como la siguiente:

CÓDIGO HTTP: 206

Scroll to Top