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 Equivalentes de Servicios Públicos Domiciliarios, Notas de ajuste crédito y debito.
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.
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 documentos equivalentes, es decir mas de un documento, se debe enviar cada petición con intervalo de 3 segundos como mínimo para evitar el cruce de peticiones.
Crear Documento Equivalente SPD
| CABECERA | VALOR |
| Content-Type | application/json |
| Authorization | token de usuario |
METODO : "POST"
Propiedades Adicionales
Agregar Acuerdos de Pago
Agregar Información Residuos
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 del documento equivalente
Nota Adicional
Para el documento equivalente, 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 del documento POS 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 |
| 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 |
| extensiones | 1..1 | Datos donde se describe la informacion de Servicios Publicos Domiciliarios | ||
| UBLExtension.serviciosPublicos | 1..1 | 1 | Información correspondiente al servicio público facturado | |
| informacionServicio.id.value | String | 1..1 | 50 | Número de consecutivo de linea |
| informacionServicio.id.schemeID | String | 1..1 | 50 | Se informa SPD para todas las UBLExtension que pertenecen a empresas de servicios públicos |
| informacionServicio.nombreServicio | String | 1..1 | 100 | Nombre del servicio facturado |
| informacionServicio.nombreEmpresaServicio | String | 1..1 | 100 | Nombre de la Empresa SPD que emite este DE |
| informacionServicio.nombreEmpresaRecaudo | String | 1..1 | 100 | Nombre de la Empresa SPD a cargo del recaudo |
| ExtensionContent.tipo | String | 1..1 | 100 | Información de la extension relacionada con el servicio prestado |
| ExtensionContent.idContrato | String | 0..1 | 100 | Número del contrato SPD |
| ExtensionContent.fecha | String | 0..1 | 10 | Fecha de generación del contrato |
| ExtensionContent.notas | String | 0..N | 500 | Campo adicional para información sobre el contrato o servicio |
| ExtensionContent.empresaPrestadoraServicio | 0..N | 1 | Información para identificación de un tercero | |
| empresaPrestadoraServicio.identificacion | 0..1 | 10 | Información documento de la empresa prestadora del servicio | |
| empresaPrestadoraServicio.identificacion.numero | String | 0..N | 10 | Numero de documento de identidad |
| empresaPrestadoraServicio.identificacion.tipo | String | 0..N | 1..4 | Identificador del tipo de documento de identidad |
| empresaPrestadoraServicio.identificacion.dv | String | 0..N | 0..N | Digito de verificacion del NIT |
| empresaPrestadoraServicio.identificacion.nombre | String | 0..N | 0..N | Nombre empresa prestadora del servicio |
| ExtensionContent.suscriptor | String | 0..1 | 1 | Datos del suscriptor y/o usuario |
| suscriptor.nombre | String | 0..N | 500 | Nombre del suscriptor y/o usuario |
| suscriptor.direccion.ubicacion | String | 0..N | 100 | Direccion del suscriptor y/o usuario |
| suscriptor.direccion.ciudad | String | 0..N | 60 | Municipio del suscriptor y/o usuario |
| suscriptor.direccion.departamento | String | 0..N | 60 | Nombre del Departamento |
| suscriptor.direccion.pais | String | 0..N | 100 | Informacion del pais |
| suscriptor.direccion.estrato | String | 0..N | 100 | Informacion sobre el estrato o tipo de plan |
| suscriptor.email | String | 0..N | 100 | Correo electrónico de contacto |
| ExtensionContent.consumoSuscriptor | String | 0..1 | 1 | Informacion de valores que se aplican al servicio facturado |
| ExtensionContent.consumoSuscriptor.ciclo | String | 0..1 | 1 | Informacion del ciclo facturado |
| consumoSuscriptor.ciclo.duracion | String | 0..1 | 50 | Cantidad del servicio facturado. |
| consumoSuscriptor.ciclo.peridiocidad | String | 0..1 | 100 | Ciclo de facturación de ESP |
| consumoSuscriptor.consumo | String | 0..1 | 1 | Informacion de consumo del servicio facturado |
| consumoSuscriptor.consumo.consumoParcial | String | 0..N | 1 | Informacion de consumo parcial |
| consumoParcial.cantidadConsumo | String | 0..N | 1 | Informacion de cantidad de consumo el periodo facturado |
| consumoParcial.cantidadConsumo.cantidad | String | 0..N | 100 | Cantidad de unidades consumidas |
| consumoParcial.cantidadConsumo.unidad | String | 0..1 | 10 | Unidad de medida |
| consumoParcial.valorTotalServicio | String | 0..1 | 10 | Informacion total del servicio consumido |
| consumoParcial.valorTotalServicio.valor | String | 0..1 | 1..3 | Valor total del servicio consumido |
| consumoParcial.valorTotalServicio.moneda | String | 0..1 | 10 | Código de moneda |
| consumoParcial.precioConsumo.unidadesConsumo | String | 0..1 | 10 | Informacion de la cantidad consumida |
| precioConsumo.unidadesConsumo.cantidad | String | 0..1 | 10 | Cantidad consumida del servicio facturado |
| precioConsumo.unidadesConsumo.unidad | String | 0..1 | 1 | Unidad de medida |
| precioConsumo.valorParcialConsumo.valor | String | 0..1 | 1 | Valor parcial del consumo |
| precioConsumo.valorParcialConsumo.moneda | String | 0..1 | 10 | Código de moneda |
| consumoParcial.descuentosCreditosAlItem | String | 0..1 | 1 | Informacion de valores créditos o descuentos |
| consumoParcial.descuentosCreditosAlItem.id | String | 0..N | 1 | Consecutivo del identificador del crédito |
| consumoParcial.descuentosCreditosAlItem.razon | String | 0..1 | 1 | Razón del valor credito |
| descuentosCreditosAlItem.razon.total.valor | String | 0..1 | 100 | Valor total del descuento o valor credito |
| descuentosCreditosAlItem.razon.total.moneda | String | 0..1 | 10 | Código de moneda |
| consumoParcial.recargosDebitosAlItem | String | 0..1 | 1 | Informacion de valores debitos o recargos |
| recargosDebitosAlItem.id | String | 0..1 | 1 | Consecutivo del identificador del débito |
| recargosDebitosAlItem.razon | String | 0..1 | 1 | Razón del valor débito |
| recargosDebitosAlItem.razon.total.valor | String | 0..1 | 100 | Valor total del cargo o valor débito |
| recargosDebitosAlItem.razon.total.moneda | String | 0..1 | 10 | Código de moneda |
| consumoParcial.valorUnitario | String | 0..1 | 10 | Informacion del valor unitario |
| consumoParcial.valorUnitario.precio | String | 0..1 | 10 | Valor por unidad del producto o servicio |
| consumoParcial.valorUnitario.precio.valor | String | 0..1 | 100 | Valor unitario del producto |
| consumoParcial.valorUnitario.precio.moneda | String | 0..1 | 10 | Código de moneda |
| consumoParcial.valorUnitario.cantidadReal | String | 0..1 | 10 | Informacion de la cantidad del servicio prestado |
| valorUnitario.cantidadReal.cantidad | Númerico | 0..1 | 10 | Cantidad real sobre la cual el precio aplica |
| valorUnitario.cantidadReal.unidad | String | 0..1 | 10 | Unidad de medida |
| consumoParcial.lecturaContador | String | 0..N | 10 | Informacion de los datos del medidor |
| consumoParcial.lecturaContador.numeroContador | String | 0..1 | 10 | Referencia del contador |
| lecturaContador.fechaLecturaAnterior | String | 0..1 | 10 | Fecha de lectura del medidor del mes anterior |
| lecturaContador.unidadesLecturaAnterior | String | 0..1 | 10 | Unidades facturadas del servicio del mes anterior |
| lecturaContador.unidadesLecturaAnterior.cantidad | String | 0..1 | 10 | Cantidad facturada |
| lecturaContador.unidadesLecturaAnterior.unidad | String | 0..1 | 100 | Unidad de medida |
| lecturaContador.fechaLecturaActual | String | 0..1 | 10 | Fecha actual de lectura del medidor |
| lecturaContador.unidadesLecturaActual | String | 0..1 | 100 | Unidades obtenidas en la lectura del medidor. |
| lecturaContador.unidadesLecturaActual.cantidad | String | 0..1 | 10 | Cantidad facturada |
| lecturaContador.unidadesLecturaActual.unidad | String | 0..1 | 100 | Unidad de medida |
| consumoParcial.metodoLectura | String | 0..1 | 1000 | Informacion del metodo de lectura |
| consumoParcial.duracionPeridoFacturado | String | 0..1 | 1000 | Informacion del servicio sobre el periodo facturado. |
| duracionPeridoFacturado.duracion | String | 0..1 | 10 | Cantidad de duracion del periodo |
| duracionPeridoFacturado.peridiocidad | String | 0..1 | 50 | Unidad de medida |
| 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 |
| 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 |
| Nombre | Código |
|---|---|
| SERVICES_SPD | SPD |
| OTHERCOMPANY_SPD | OTHER |
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