Guía Técnica Para Consumo API Documento Soporte / Nota de Ajuste

Por /

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

Nuestro servicio incluye un riguroso proceso de verificación y validación de sus documentos, 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.

Las acciones disponibles para la API son:

  • Crear Documento Soporte
  • Crear Nota de Ajuste

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/


Tener en cuenta que para el campo cliente/proveedor con Procedencia tipo RESIDENTE, únicamente se permite el tipo de identificación NIT cuyo código es NI.

Crear Documento Soporte

CABECERAS:

CABECERASVALOR
Content-Type application/json
Authorizationtoken de usuario

METODO : "POST"

{
  • "nit": "12345",
  • "numeroResolucion": "196547852",
  • "fechaGeneracion": "2024-01-10 18:44:34",
  • "fechaVencimiento": "2024-07-15 18:44:38",
  • "numeroDtoComercial": "DS1",
  • "formaPago": "CREDITO",
  • "mediosPago": "10",
  • "total": 165000,
  • "numComprobanteFisico": "JP015",
  • "items": [
    • {
      • "nombreItem": "Arroz bolsa",
      • "cantidad": 11,
      • "precioUnitario": 15000,
      • "precioReferencia": 0,
      • "descuento": 0,
      • "cargo": 0,
      • "codigo": "AR01",
      • "unidad": "94",
      • "fechaCompra": "2022-07-10",
      • "formaTransmision": "POR_OPERACION",
      • "observacion": "Observación del ítem"
      ...}// 11 items
    ...]// 1 item    ,
  • "proveedor": {
    • "tipoIdentificacion": "NI",
    • "numIdentificacion": "1584516160",
    • "razonSocial": "Juan Diego Parra Linares",
    • "naturaleza": "NATURALES",
    • "responsabilidadesFiscales": "R-99-PN",
    • "direccion": "Carrera 10 N 42-18",
    • "ciudad": "12800",
    • "email": "soporte@clarisa.co",
    • "telefono": "",
    • "procedencia": "RESIDENTE",
    • "respTributarias": "IVA"
    ...}// 11 items    ,
  • "observacion": "Esta es la observación"
...}// 12 items

Información adicional para enviar a nivel de ítem


{
  • "retenciones": [
    • {
      • "retencion": 41,
      • "valor": 3401,
      • "porcentaje": 10,
      • "baseGravable": 34010
      ...}// 4 items
    ...]// 1 item
...}// 1 item

NOTA: Si la forma de generación y transmisión es POR_OPERACION el campo fechaCompra debe ser la fecha actual es decir misma fecha de generación del documento. Si es por ACUMULADO_SEMANAL el campo fechaCompra solo puede ser dentro de los 6 días anteriores a la fecha actual.


Petición:


Nombre Formato Tamaño Descripción
NIT Alfanumérico 100 NIT de la empresa sin dígito de verificación
numeroResolucion numérico 100 Número de resolucion aprobada en la DIAN
fechaGeneracion String 100 Fecha de generación del documento electrónico (Formato: yyyy-MM-dd hh:mm:ss)
fechaVencimiento String 100 Fecha de vencimiento del documento electrónico(Formato: yyyy-MM-dd hh:mm:ss)
numeroDtoComercial Alfanumérico 100 Número del documento electrónico
formaPago String 100 Código de la DIAN asociado a la forma de pago del documento electrónico. Ver tabla valores para forma de Pago
mediosPago Alfanumerico 100 Código de la DIAN asociado a los medios de pago del documento electrónico. Ver tabla valores para medios de Pago
total numérico 100 Valor total del documento electrónico.
numComprobanteFisico Alfanumérico 100 Número del comprobante, vacio si no se tiene el número.
Items Array [] Lineas de la factura.
nombreItem String 100 Nombre del producto vendido
cantidad numero 100 Cantidad vendida del ítem
precioUnitario numérico 100 Precio de venta unitario del producto
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 descuento = 100 o si precioUnitario = 0
descuento numérico 100 Valor descuento aplicado al ítem.
cargo numérico 100 Precio de cargo del producto
código Alfanumérico 100 Código del producto vendido.
unidad Alfanumerico 100 código de la DIAN de la Unidad del producto. REVISAR tabla Valores para unidad
fechaCompra String 100 Fecha adquisicion del producto (Formato: yyyy-MM-dd)
formaTransmision String 100 Es la forma de generación y transmisión para cada item, ver tabla Valores Formas de Transmisión
observacion String 100 Observaciones para el item
proveedor String Datos del Cliente/Proveedor del documento electrónico
tipoIdentificacion Alfanumérico 100 Código del tipo de identificación, véase la lista tipo de identificación.
numIdentificacion númerico 100 Número de identificación de cliente/proveedor, sin dígito de verificación.
razonSocial Alfanumérico 100 Cliente/Proveedor: Razón social o Nombre
naturaleza String 100 Código de la naturaleza del cliente, véase valores para Naturaleza
responsabilidadesFiscales Alfanumérico 100 Código de responsabilidades fiscales, véase tabla Responsabilidades fiscales Cliente/Proveedor
direccion Alfanumérico 100 Dirección Cliente/Proveedor
ciudad Alfanumérico 100 Código DANE de la ciudad. La ciudad del cliente, véase la tabla valores para ciudad
email String 100 Correo electronico del Cliente/Proveedor
telefono String 100 Numero de telefono del Cliente/Proveedor
procedencia String 100 Procedencia del cliente, véase la tabla valores para Procedencia
direccion Alfanumérico 100 Dirección Cliente/Proveedor
respTributarias Alfanumérico 100 Códigos de Responsabilidad Tributaria, ver tabla Responsabilidades Tributarias Cliente/Proveedor


Nombre Código
Contado CONTADO
Crédito CREDITO


Nombre Código
Otro* 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 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

Forma de Transmisión Valor
Por Operación POR_OPERACION
Acumulado Semanal ACUMULADO_SEMANAL


Nombre Codigo
NIT NI
Cedula de extranjeria CE
NIT de otro pais NO
Pasaporte PA
PEP PE
Tarjeta de extranjeria TE


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


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 Aplica - Otros R-99-PN


Ciudad Extranjera Codigo
Cupertino - California - US US002
New York - US US003
Hong Kong CN002
Consultar API Ciudades o Revisar Excel para Ciudades de Colombia


Nombre Codigo
Residente RESIDENTE
No residente NO_RESIDENTE


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
Arrendamiento de bienes inmuebles (declarantes) 1
Compras generales (declarantes) 3
Compras generales (no declarantes) 4
Honorarios y comisiones (no declarantes)) 5
Honorarios y comisiones (personas jurídicas) 6
Servicios de aseo y vigilancia 7
Servicios de hoteles y restaurantes (no declarantes) 8
Servicios generales (declarantes) 9
Servicios generales (no declarantes) 10
ReteICA 11
ReteIVA 15% 12
Transporte de Carga 13
ReteIVA 100% 16
Arrendamiento de bienes inmuebles (no declarantes) 17
Arrendamiento de bienes muebles 18
Compras con tarjeta débito o crédito 19
Compras de bienes o productos agrícolas o pecuarios sin procesamiento industrial 20
Compras de bienes o productos agrícolas o pecuarios con procesamiento industrial (declarantes) 21
Compras de bienes o productos agrícolas o pecuarios con procesamiento industrial declarantes (no declarantes) 22
Compras de café pergamino o cereza 23
Compras de combustibles derivados del petróleo 24
Enajenación de activos fijos de personas naturales (notarías y tránsito son agentes retenedores) 25
Compras de vehículos 26
Compras de bienes raíces cuya destinación y uso sea vivienda de habitación (por las primeras 20.000 UVT, es decir hasta $637.780.000) 27
Compras de bienes raíces cuya destinación y uso sea vivienda de habitación (exceso de las primeras 20.000 UVT, es decir superior a $637.780.000) 28
Compras de bienes raíces cuya destinación y uso sea distinto a vivienda de habitación 29
Por emolumentos eclesiásticos (declarantes) 30
Por emolumentos eclesiásticos (no declarantes) 31
Servicios de transporte de carga 32
Servicios de transporte nacional de pasajeros por vía terrestre (declarantes) 33
Servicios de transporte nacional de pasajeros por vía terrestre (no declarantes) 34
Servicios de transporte nacional de pasajeros por vía aérea o marítima/td> 35
Servicios prestados por empresas de servicios temporales (sobre AIU) 36
Servicios prestados por empresas de vigilancia y aseo (sobre AIU) 37
Servicios integrales de salud prestados por IPS 38
Servicios de hoteles y restaurantes (declarantes) 39
Otros ingresos tributarios (declarantes) 40
Otros ingresos tributarios (no declarantes) 41
Honorarios y comisiones personas naturales que suscriban contrato o cuya sumatoria de los pagos o abonos en cuenta superen las 3.300 UVT ($105.135.000) 42
Servicios de licenciamiento o derecho de uso de software 43
Intereses o rendimientos financieros 44
Rendimientos financieros provenientes de títulos de renta fija 45
Loterías, rifas, apuestas y similares 46
Retención en colocación independiente de juegos de suerte y azar 47
Contratos de construcción y urbanización 48


NOTA: Puedes descargar el siguiente archivo de excel con las ciudades de Colombia 

Ciudades-4Descargar

Correcto

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

CÓDIGO HTTP: 200

{
  • "data": {
    • "cuds": "526651041429566a5813abbc41a0a6e5f1d6b0f6f486ceedc8f65aa74b12ee1e45281b9a9556cd6474b6",
    • "fechaValidacion": "2025-01-20T11:15:22",
    • "numero": "DS1",
    • "estadoEmision": "Reportada"
    ...}// 4 items    ,
  • "lastAction": "Guardar Documento Soporte",
  • "success": true,
  • "textResponse": "Documento soporte reportado",
  • "titleResponse": "SUCCESS"
...}// 5 items

  Error

Si la solicitud no es correcta, recibirá la respuesta según error como el siguiente:

CÓDIGO HTTP: 400 | 401 | 500

{
  • "errores": {
    • "errores": [
      • {
        • "codError": "",
        • "errorMessage": "La numeración con resolución: 1234570 está vencida. Fecha de vencimiento: 2025-01-17"
        ...}// 2 items
      ...]// 1 item      ,
    • "totalErrores": 1
    ...}// 2 items    ,
  • "lastAction": "Guardar Documento Soporte",
  • "success": false,
  • "textResponse": "Fallo al generar documento soporte desde API",
  • "titleResponse": "FAILED"
...}// 5 items

2 Crear Nota de Ajuste

CABECERAS :

CABECERAVALOR
Content-Type application/json
Authorizationtoken de usuario

METODO : "POST"

{
  • "nit": "12345",
  • "fechaGeneracion": "2024-01-11 11:00:00",
  • "numeroDtoComercial": "NADS1",
  • "numDocumentoSoporte": "DS1",
  • "motivo": "Anular DS"
...}// 5 items

Correcto

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

CÓDIGO HTTP: 200

{
  • "data": {
    • "numero": "NADS1"
    ...}// 1 item    ,
  • "lastAction": "Crear nota de ajuste",
  • "success": true,
  • "textResponse": "Nota de ajuste reportada",
  • "titleResponse": "SUCCESS"
...}// 5 items

Error

Si la solicitud no es correcta, recibirá la respuesta de error como el siguiente:

CÓDIGO HTTP: 400

{
  • "errores": {
    • "errores": [
      • {
        • "codError": "VDNOA03",
        • "errorMessage": "Documento soporte asociado no existe"
        ...}// 2 items
      ...]// 1 item      ,
    • "totalErrores": 1
    ...}// 2 items    ,
  • "lastAction": "Crear nota de ajuste",
  • "success": false,
  • "textResponse": "Fallo al generar nota de ajuste",
  • "titleResponse": "FAILED"
...}// 5 items