Guía Técnica Para Consumo API Facturación

Clarisa ofrece una API que le permite a su sistema integrarse y realizar factura electrónica, nota crédito con referencia a factura , nota crédito sin referencia a factura y nota débito.
Contamos con la verificación y validación de sus facturas para lograr ser aceptadas y reportadas a la DIAN .

Las acciones disponibles para la API de facturación son:

  • Crear Factura Electrónica
  • Crear Nota Crédito
  • Crear Nota Crédito Sin Referencia a Factura
  • Crear Nota Débito
  • Crear Nota Débito Sin Referencia a Factura

Importante !

Para el envío masivo de facturas, es decir mas de una factura, se debe enviar cada petición con intervalo de 5 segundos como mínimo.

Crear Factura Electrónica

CABECERAS:

CABECERASVALOR
Content-Type  application/json
Authorizationtoken de usuario

METODO : "POST"



Información adicional para enviar a nivel de ítem


Petición:


Nombre Formato Tamaño Descripción
NIT Alfanumérico 100 NIT de la empresa sin dígito de verificación
cliente Datos del Cliente del documento electrónico
cliente.nombreRazonSocial Alfanumérico 100 Cliente: Razón social o Nombre
cliente.tipoIdentificacion Alfanumérico 100 Código del tipo de identificación, véase la lista tipo de identificación.
cliente.numIdentificacion númerico 100 Número de identificación de cliente, sin dígito de verificación.
cliente.naturaleza String 100 Código de la naturaleza del cliente, véase valores para Naturaleza
cliente.direccion Alfanumérico 100 Dirección Cliente
cliente.ciudad Alfanumérico 100 Código DANE de la ciudad. La ciudad del cliente, véase la tabla valores para ciudad
cliente.telefono numérico 100 Télefono del cliente
cliente.email Alfanumérico 100 correo Electrónico
cliente.responsabilidadesFiscales Alfanumérico 100 Código de responsabilidades fiscales, véase tabla Responsabilidades fiscales cliente
cliente.respTributarias Alfanumérico 100 Código de responsabilidades tributarias, véase tabla Valores para Responsabilidades tributarias cliente
numeroDocumentoComercial numérico 100 Número del documento electrónico
fechaGeneracion String 100 Fecha de generación del documento electrónico (Formato: yyyy-MM-ddThh:mm:ss)
fechaVencimiento String 100 Fecha de vencimiento del documento electrónico(Formato: yyyy-MM-ddThh:mm:ss)
mediosPago Alfanumérico 100 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
Observación Alfanumérico 100 Observación.
formaPago numérico 100 Código de la DIAN asociado a la forma de pago del documento electrónico. revisar tabla valores para forma de Pago
total numérico 100 Valor total del documento electrónico.
ítems Array [] Lineas de la factura.
items.nombreItemVenta Alfanumérico 100 Nombre del producto vendido
items.precioVentaUnitario numérico 100 Precio de venta unitario del producto
items.precioBaseUnitario numérico 100 Precio base unitario del producto. Este atributo remplaza a items.precioVentaUnitario en caso que desee que los cálculos del item se hagan a partir del precio base y no a partir del precio con impuesto.
items.precioReferencia numérico 100 Precio de referencia del producto cuando éste se considera un regalo, es decir, su precio resultante es igual a cero. Este campo es obligatorio si items.descuentoPorcentaje = 100 o si items.precioVentaUnitario = 0 o items.precioBaseUnitario = 0
items.cantidad numérico 100 Cantidad vendida del ítem
items.impuesto Alfanúmerico 100 Impuesto aplicado, revisar tabla Valores para impuestos
items.código Alfanumérico 100 Código del producto vendido.
items.unidad Alfanumérico 100 código de la DIAN de la Unidad del producto. REVISAR tabla Valores para unidad
items.códigoDescuento Alfanuméricos 100 Código de la dian del tipo de descuento aplicado al ítem.
items.descuentoPorcentaje numérico 100 porcentaje de descuento aplicado al ítem
items.observacion Alfanumérico 100 Observación del ítem
numeroResolucion numérico 100 Número de resolucion aprobada en la DIAN
códigoDescuento Alfanumérico 100 Código de la DIAN del tipo de descuento aplicado al ítem
porcentajeDescuentoGeneral numérico 100 Porcentaje de descuento aplicado al valor total
periodoFacturacion Información del periodo de facturación asociado a la factura.
periodoFacturacion.fechaInicial String Fecha de inicio del periodo de facturación en formato YYYY-MM-DD.
periodoFacturacion.horaInicial String Hora de la fecha de inicio del periodo de facturación en formato hh:mm:ss
periodoFacturacion.fechaFinal String Fecha de inicio del periodo de facturación en formato YYYY-MM-DD
periodoFacturacion.horaFinal String Hora de la fecha de finalización del periodo de facturación en formato hh:mm:ss
urlDescargaAdjuntos Describe los datos donde el emisor dispone de la información complementaria a los documentos electrónicos que el adquiriente puede ingresar y descargar directamente sin la necesidad de ingresas credenciales (Usuario/Contraseña)
urlDescargaAdjuntos.url Dirección donde se accede a la información complementaria
urlDescargaAdjuntos.parametros Parámetros de la URL con sus respectivos valores. Cada parámetro se separa por coma “,” y a su vez el nombre y valor del parámetro va separado por el símbolo dos puntos “:”.
Ejemplo: nombre:Andrea;edad:24

Indica los parámetros:

nombre = Andrea

edad= 24

wsEntregaEventos Grupo de información utilizado para la recepción los eventos que se genere por parte de Adquiriente. Corresponde a un acuerdo o formalidad entre las partes (Emisor y Receptor).
wsEntregaEventos.url String Dirección del Web Service
wsEntregaEventos.parametros String Parámetros del Web Service con sus respectivos valores. Cada parámetro se separa por coma “,” y a su vez el nombre y valor del parámetro va separado por el símbolo dos puntos “:”.
Ejemplo: nombre:Andrea;edad:24

Indica los parámetros:

nombre = Andrea

edad= 24


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

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

Nombre Código
Gran contribuyente O-13
Autorretenedor O-15
Agente de retención en el impuesto sobre las ventas O-23
Régimen de tributación- SIMPLE O-47
No responsable R-99-PN

Nombre Código
Impuesto al valor agregado IVA
Impuesto Nacional al Consumo INC
IVA + INC IVA_E_INC
No aplica NO_APLICA

Nombre Código
Responsable del impuesto sobre las ventas - IVA IMPUESTO_SOBRE_VENTAS
No responsable de IVA NO_RESPONSABLE_IVA

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

Nombre código
Descuento por impuesto asumido 00
Pague uno lleve otro 01
Descuentos contractulales 02
Descuento por pronto pago 03
Envío gratis 04
Descuentos específicos por inventarios 05
Descuento por monto de compras 06
Descuento de temporada 07
Descuento por actualización de productos / servicios 08
Descuento general 09
Descuento por volumen 10
Otro descuento 11

Descripción código
Excluido de impuesto EXCLUIDO
Exento de impuesto EXENTO
Impuesto al consumo 4% IMPUESTO_CONSUMO_4
Impuesto al consumo 8% IMPUESTO_CONSUMO_8
Impuesto al consumo 16% IMPUESTO_CONSUMO_16
IVA 19% + INC Bolsas BOLSA_IVA
IVA 5% IVA_5
IVA 19% IVA_19

Código naturaleza Descripción
NATURALES Persona natural
JURIDICAS Persona Jurídica

Revisar el excel con los datos de las ciudades

Consideraciones:

  •  Si desea que el origen de los cálculos de los ítems de la factura sea el precio con impuesto, debe enviar el atributo items.precioVentaUnitario. Si por el contrario desea que el origen de los cálculos sea el precio base unitario, envíe el atributo items.precioBaseUnitario.
  • No envíe en un mismo ítem los atributos items.precioBaseUnitario e items.precioVentaUnitario a la vez.

Nota:

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


Si lo desea puede acceder directamente a nuestra API de ciudades y cargar la ciudad de ese modo, Guía Técnica para Consumo API Ciudades


Respuesta:


Nombre Tipo dato Descripción
success Booleano Determina si la operación fué exitosa o no
titleResponse Alfanumérico Título de la respuesta
textResponse Alfanumérico Texto de la respuesta
lastAction Alfanumérico Nombre de la acción bajo la cual se respondió esta respuesta
data Datos de respuesta
data.numeroFactura Alfanúmerico Número de la factura creada
data.urlAcuseRecibido Alfanúmerico URL para acusar recibido de la información
data.cufe Alfanumérico Cufe de la Factura electrónica creada
errores Alfanumérico Detalles globales de errores.
total_errores Numérico Número total de errores
errores.errores Array Array, con la lista de errores.
errores.errores.codError Alfanúmerico Código de error.
errores.errores.errorMessage Alfanúmerico Mensaje del error.


En caso de que no se pueda obtener la información de la factura se debe tener en cuenta la variable success y los valores detitleResponse y textResponse para poder mostrar los mensajes respectivos al usuario. La variable titleResponse contiene el código del error y la variable textResponse contiene la descripción del error la cual debe ser mostrada al usuario. Si son errores por validación de datos, en el data se retorna el total de errores  y un array de los mismos.

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: 400 | 401 | 500


Crear Nota Débito (Con Referencia a Factura / Sin Referencia a Factura)

Contamos con la verificación y validación de sus notas débito para lograr ser aceptadas y reportadas a la DIAN :

CABECERAS:

CABECERAVALOR
Content-Type  application/json
Authorizationtoken de usuario

NOTA: Para el reporte de una nota debito Sin referencia debe agregar "tipoDocumentoND": "SIN_REFERENCIA_FACTURA" , y no agregar número de factura asociada, ejemplo:

Petición


Nombre del campo Formato Tamaño Descripción
nit Alfanumérico 100 Hace referencia del NIT de la empresa.
numeroFacturaAsociada String 100 Numero de la factura asociada a la nota débito.
tipo String 100 Código de la DIAN que identifica el Tipo de la nota débito,Son: INTERESES GASTOS_POR_COBRAR CAMBIO_POR_COBRAR OTRO
numeroDocumentoComercial String 100 Numero de la Nota Débito
codigoDescuento String 100 Código de la dian del tipo de descuento aplicado al item, vease la tabla Valores para codigoDescuento
porcentajeDescuentoGeneral String 100 Porcentaje de descuento aplicado al valor total
cliente Datos del Cliente del documento electrónico
cliente.nombreRazonSocial Alfanumérico 100 Cliente: Razón social o Nombre
cliente.tipoIdentificacion Alfanumérico 100 Codigo del tipo de identificación, vease la lista tipo de identificación.
cliente.numIdentificacion númerico 100 Número de identificación de cliente
cliente.naturaleza String 100 Naturaleza del cliente Juridica o Natural revisar tabla Naturaleza
cliente.direccion Alfanumérico 100 Dirección Cliente
cliente.ciudad numérico 100 Identificador de la ciudad del cliente, vease la tabla ciudad
cliente.telefono numérico 100 Telefono del cliente
cliente.email Alfanumérico 100 correo Electronico
cliente.responsabilidadesFiscales Alfanumérico 100 Código de responsabilidades fiscales, véase tabla Responsabilidades fiscales cliente
cliente.respTributarias Alfanumérico 100 Código de responsabilidades tributarias, véase tabla Valores para Responsabilidades tributarias cliente
numeroDocumentoComercial numérico 100 Numero del documento electrónico
fechaGeneracion String 100 Fecha de generación del documento electrónico (Formato: yyyy-MM-ddThh:mm:ss)
fechaVencimiento String 100 Fecha de vencimiento del documento electrónico(Formato: yyyy-MM-ddThh:mm:ss)
mediosPago Alfanumérico 100 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 medios de pago
Observación Alfanumérico 100 Observación.
formaPago numérico 100 Código de la DIAN asociado a la forma de pago del documento electrónico. revisar tablaformaPago
total numérico 100 Valor total del documento electrónico.
items Array [] Lineas de la Nota debito.
items.nombreItemVenta Alfanumérico 100 Nombre del producto vendido
items.precioVentaUnitario numérico 100 Precio de venta unitario del producto
items.precioBaseUnitario numérico 100 Precio base unitario del producto. Este atributo remplaza a items.precioVentaUnitario en caso que desee que los cálculos del item se hagan a partir del precio base y no a partir del precio con impuesto.
items.precioReferencia numérico 100 Precio de referencia del producto cuando éste se considera un regalo, es decir, su precio resultante es igual a cero. Este campo es obligatorio si items.descuentoPorcentaje = 100 o si items.precioVentaUnitario = 0 o items.precioBaseUnitario = 0
items.cantidad numérico 100 Cantidad vendida del item
items.impuesto ImpuestoEnum 100 Impuesto aplicado, revisar tabla ImpuestoEnum
items.codigo Alfanumérico 100 Código del producto vendido.
items.unidad Alfanumérico 100 código de la DIAN de la Unidad del producto. REVISAR tabla unidad
items.codigoDescuento Alfanuméricos 100 Código de la dian del tipo de descuento aplicado al item.
items.descuentoPorcentaje numérico 100 porcentaje de descuento aplicado al item
items.observacion Alfanumérico 100 Observación del item

Nombre codigo
Descuento por impuesto asumido 00
Pague uno lleve otro 01
Descuentos contractulales 02
Descuento por pronto pago 03
Envío gratis 04
Descuentos específicos por inventarios 05
Descuento por monto de compras 06
Descuento de temporada 07
Descuento por actualización de productos / servicios 08
Descuento general 09
Descuento por volumen 10
Otro descuento 11

Consideraciones:

  •  Si desea que el origen de los cálculos de los ítems de la factura sea el precio con impuesto, debe enviar el atributo items.precioVentaUnitario. Si por el contrario desea que el origen de los cálculos sea el precio base unitario, envíe el atributo items.precioBaseUnitario.
  • No envíe en un mismo ítem los atributos items.precioBaseUnitario e items.precioVentaUnitario a la vez.

Respuesta:


Nombre Tipo dato Descripción
success Booleano Determina si la operación fué exitosa o no
titleResponse Alfanumérico Título de la respuesta
textResponse Alfanumérico Texto de la respuesta
lastAction Alfanumérico Nombre de la acción bajo la cual se respondió esta respuesta
data.numeroNotaDebito Alfanumérico Datos de respuesta
data.urlAcuseRecibido Alfanúmerico URL para acusar recibido de la información
data.cufe Alfanumérico Cufe de la nota débito creada


  Correcto

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


Error

Si la solicitud no es correcta, recibirás un estado HTTP o por consiguiente un mensaje explicando el posible error.


Crear Nota Crédito (Con Referencia a Factura / Sin Referencia a Factura)

Contamos con la verificación y validación de sus notas crédito para lograr ser aceptadas y reportadas a la DIAN :

CABECERAS:

CABECERASVALOR
Content-Type  application/json
Authorizationtoken de usuario

METODO: "POST"


NOTA: Para el reporte de una nota crédito Sin referencia debe agregar "tipoDocumentoNC": "SIN_REFERENCIA_FACTURA" , y no agregar número de factura asociada, ejemplo:


Consideraciones:

  •  Si desea que el origen de los cálculos de los ítems de la factura sea el precio con impuesto, debe enviar el atributo items.precioVentaUnitario. Si por el contrario desea que el origen de los cálculos sea el precio base unitario, envíe el atributo items.precioBaseUnitario.
  • No envíe en un mismo ítem los atributos items.precioBaseUnitario e items.precioVentaUnitario a la vez.

Petición


Nombre del campo Formato Tamaño Descripción
nit Alfanumérico 100 Hace referencia del NIT de la empresa.
numeroDocumentoComercial numérico 100 Numero de la nota crédito
fechaGeneracion String 100 Fecha de generación del documento electrónico (Formato: yyyy-MM-ddThh:mm:ss)
fechaVencimiento String 100 Fecha de vencimiento del documento electrónico(Formato: yyyy-MM-ddThh:mm:ss)
numeroFacturaAsociada String 100 Numero de la factura asociada a la nota crédito.
tipo String 100 Código de la DIAN que identifica el Tipo de la nota crédito, puede ser de tipo DEVOLUCION_BIENES o ANULACION
mediosPago Alfanumérico 100 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 medios de pago
Observación Alfanumérico 100 Observación.
formaPago numérico 100 Código de la DIAN asociado a la forma de pago del documento electrónico. revisar tablaformaPago
total numérico 100 Valor total del documento electrónico.
cliente Datos del Cliente del documento electrónico
cliente.nombreRazonSocial Alfanumérico 100 Cliente: Razón social o Nombre
cliente.tipoIdentificacion Alfanumérico 100 Codigo del tipo de identificación, vease la lista tipo de identificación.
cliente.numIdentificacion númerico 100 Número de identificación de cliente
cliente.naturaleza String 100 Naturaleza del cliente Juridica o Natural revisar tabla Naturaleza
cliente.direccion Alfanumérico 100 Dirección Cliente
cliente.ciudad numérico 100 Identificador de la ciudad del cliente, si la factura a la que se hace la nota es de tipo exportación. De lo contrario, enviar código DANE de la ciudad, véase la tabla ciudad
cliente.telefono numérico 100 Telefono del cliente
cliente.email Alfanumérico 100 correo Electronico
cliente.responsabilidadesFiscales Alfanumérico 100 Código de responsabilidades fiscales, véase tabla Responsabilidades fiscales cliente
cliente.respTributarias Alfanumérico 100 Código de responsabilidades tributarias, véase tabla Valores para Responsabilidades tributarias cliente
items Array [] Lineas de la Nota Credito.
items.nombreItemVenta Alfanumérico 100 Nombre del producto vendido
items.precioVentaUnitario numérico 100 Precio de venta unitario del producto
items.precioBaseUnitario numérico 100 Precio base unitario del producto. Este atributo remplaza a items.precioVentaUnitario en caso que desee que los cálculos del item se hagan a partir del precio base y no a partir del precio con impuesto.
items.precioReferencia numérico 100 Precio de referencia del producto cuando éste se considera un regalo, es decir, su precio resultante es igual a cero. Este campo es obligatorio si items.descuentoPorcentaje = 100 o si items.precioVentaUnitario = 0 o items.precioBaseUnitario = 0
items.cantidad numérico 100 Cantidad vendida del item
items.impuesto ImpuestoEnum 100 Impuesto aplicado, revisar tabla ImpuestoEnum
items.codigo Alfanumérico 100 Código del producto vendido.
items.unidad Alfanumérico 100 código de la DIAN de la Unidad del producto. REVISAR tabla unidad
items.codigoDescuento Alfanuméricos 100 Código de la dian del tipo de descuento aplicado al item.
items.descuentoPorcentaje numérico 100 porcentaje de descuento aplicado al item
items.observacion Alfanumérico 100 Observación del item


Respuesta


Nombre Tipo dato Descripción
success Booleano Determina si la operación fué exitosa o no
titleResponse Alfanumérico Título de la respuesta
textResponse Alfanumérico Texto de la respuesta
lastAction Alfanumérico Nombre de la acción bajo la cual se respondió esta respuesta
data.numeroNotaCredito Alfanumérico Datos de respuesta
data.urlAcuseRecibido Alfanúmerico URL para acusar recibido de la información
data.cufe Alfanumérico Cufe de la nota crédito creada
errores Alfanumérico Objeto con detalles globales de errores.
total_errores Numérico Número total de errores
errores.errores Array Array, con la lista de errores.
errores.errores.codError Alfanúmerico Código de error.
errores.errores.errorMessage Alfanúmerico Mensaje del error.


Correcto

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

Error

Si la solicitud no es correcta, un ejemplo de respuesta será el siguiente: