Clarisa ofrece una avanzada API, diseñada para una integración sencilla, que le permitirá conectar su sistema y agilizar diversas operaciones.
Este servicio describe la funcionalidad de la API para la creación y gestión de Notas Crédito con referencia a factura del sector salud bajo el tipo de operación SS-SINAPORTE. Incluye un riguroso proceso de verificación y validación, asegurando la aceptación y correcta presentación del documento ante la DIAN .
Antes de continuar:
Para utilizar cualquier servicio de la API, es importante contar con un token de autenticación y autorización. Si necesita asistencia para obtenerlo, consulte la documentación detallada que se indica en el siguiente link.
https://ayuda.clarisa.co/guia-para-consumir-api-de-login/
Importante !
Para el envío masivo de documentos electrónicos, es decir mas de una Nota crédito, se debe enviar cada petición con intervalo de 3 segundos como mínimo para evitar el cruce de peticiones.
Documentación
| Nombre | Formato | Oc | Tamaño | Descripción |
|---|---|---|---|---|
| NIT | Alfanumérico | 1..1 | 3-13 | NIT de la empresa sin dígito de verificación |
| prefijoDcto | Alfanumérico | 0..1 | 0-4 | Prefijo asociado a la numeración |
| tipo | Alfanumérico | 1..1 | 0-4 | Tipo de ajuste |
| motivo | Alfanumérico | 0..1 | 0-4 | Razon de ajuste |
| consecutivoDcto | Numérico | 1..1 | 1-9 | Número del consecutivo asociado al documento |
| 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 DIAN asociado a la forma de pago del documento electrónico. revisar tabla valores para forma de Pago |
| docReferenciados | Array [] | 1..N | 3 | Documento al cual se aplica el ajuste |
| docReferenciados.tipoReferencia | Alfanumérico | 1..1 | 4-1000 | FACTURA_NACIONAL |
| docReferenciados.numeroDocumento | Alfanumérico | 1..1 | 4-1000 | Prefijo y consecutivo documento electrónico |
| docReferenciados.uuid | Alfanumérico | 1..1 | 96 | CUFE de la factura electronica |
| docReferenciados.fechaGeneracion | String | 1..1 | 10 | Fecha de generacion del documento electrónico(Formato: yyyy-MM-dd) |
| 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 observación en el documento |
| total | numérico | 1..1 | 0-15 Dec 0-6 | Valor total del documento electrónico. |
| periodoFacturacion | 1..1 | Intervalo de fechas para informar el periodo que se afecta | ||
| periodo.fechaInicial | String | 1..1 | 10 | Fecha de inicio del periodo de facturación (Formato: yyyy-MM-dd) |
| periodo.horaInicial | String | 1..1 | 10 | Hora de inicio del periodo de facturación (Formato: yyyy-MM-dd) |
| periodo.fechaFinal | String | 1..1 | 10 | Fecha de fin del periodo de facturación (Formato: yyyy-MM-dd) |
| periodo.horaFinal | String | 1..1 | 10 | Hora de fin del periodo de facturación (Formato: yyyy-MM-dd) |
| í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.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 | 0..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 | numérico | 1..1 | 4 | Valor del impuesto fijado segun normativa |
| items.impuestos.factor | numérico | 0..1 | 0-15 Dec 0-2 | Atributo que solo aplica a impuesto que requieren un cálculo especial |
| listaDescuentosCargos | Array [] | 0..N | Descuento o recargos asociados a la factura | |
| listaDescuentosCargos.tipo | String | 1..1 | 10 | Indicador si pertenece a un descuento o un cargo Valores Descuento o Cargo |
| listaDescuentosCargos.codigo | String | 1..1 | 2 | Indicador de la condicion del Descuento o Cargo Valores el código del Descuento o Cargo |
| listaDescuentosCargos.valor | numérico | 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 una observación al Descuento o Cargo |
| extensiones | 1..1 | Campo para indicar extensión en salud | ||
| extensiones.salud | 1..1 | Datos del sector salud | ||
| salud.tipoOperacion | Alfanumérico | 1..1 | 5-255 | Tipo de operacion usado en salud Valores para Tipo de operacion |
| salud.codigoPrestador | Alfanumérico | 1..1 | 10 | Código otorgado por el Ministerio de Salud y Protección Social al prestador de servicios de salud |
| salud.modalidad | numérico | 1..1 | 2 | Modalidad de contratación y de pago pactada objeto de facturación. Valores para Modalidad de Pago. |
| salud.cobertura | numérico | 1..1 | 2 | Cobertura o plan de beneficios Valores para Cobertura. |
| salud.numeroPoliza | Alfanumérico | 1..1 | 20 | SOAT o número de póliza de planes voluntarios de salud |
| salud.numeroContrato | Alfanumérico | 1..1 | 20 | Obligatorio cuando exista contrato, sino es asi debe ir vacío. |
| Nombre | Codigo |
|---|---|
| Cédula de ciudadanía | CC |
| NIT | NI |
| Registro civil | RC |
| Tarjeta de identidad | TI |
| Tarjeta de extranjería | TE |
| Cédula de extranjería | CE |
| Pasaporte | PA |
| Documento de identificación extranjero | DE |
| Permiso Especial de Permanencia | PE |
| Permiso de Protección Temporal | PT |
| Nit de otro país | NO |
| NUIP | NU |
| 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 |
| 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 |
| Descripción | Código |
|---|---|
| Si el tipoOperacion de la factura es ss-cufe | SS_CUFE |
| Si el tipoOperacion de la factura es ss-reporte | SS_REPORTE |
| Si el tipoOperacion de la factura es ss-recaudo | SS_RECAUDO |
| Si el tipoOperacion de la factura es ss-sinAporte | SS_SINAPORTE |
| Nombre del campo | Código |
|---|---|
| Pago individual por caso / Conjunto integral de atenciones / Paquete / Canasta | INDIVIDUAL |
| Pago Global Prospectivo | GLOBAL |
| Pago por capitación | CAPITACION |
| Pago por evento | EVENTO |
| Otra modalidad (específica) | OTRO(Coloque aqui otra modalidad) |
| Nombre del campo | Código |
|---|---|
| Plan de beneficios en salud financiado con UPC | 01 |
| Presupuesto máximo | 02 |
| Prima EPS, no asegurados SOAT | 03 |
| Cobertura Póliza SOAT | 04 |
| Cobertura ARL | 05 |
| Cobertura ADRES | 06 |
| Cobertura Salud Pública | 07 |
| Cobertura entidad territorial, recursos de oferta | 08 |
| Urgencias población migrante | 09 |
| Plan complementario en salud | 10 |
| Plan medicina prepagada | 11 |
| Pólizas en salud | 12 |
| Cobertura Régimen Especial o Excepción | 13 |
| Cobertura Fondo Nacional de Salud de las Personas Privadas de la Libertad | 14 |
| Particular | 15 |
| Nombre | Código |
|---|---|
| Devolución de parte de los bienes y/o no aceptación de partes del servicio | DEVOLUCION_BIENES |
| Anulación de factura electrónica | ANULACION |
| Rebaja o descuento parcial o total | REBAJA_DESCUENTO_TOTAL |
| Ajuste de precio | AJUSTE_PRECIO |
| Descuento comercial por pronto pago | DESCUENTO_PRONTO_PAGO |
| Descuento comercial por volumen de ventas | DESCUENTO_VOLUMEN_VENTAS |
Nota:
Puede descargar el siguiente archivo de excel con las ciudades de Colombia
Crear Nota Crédito a Factura de Salud SS-SinAporte
| CABECERA | VALOR |
| Content-Type | application/json |
| Authorization | token de usuario |
METODO : "POST"
NOTA: El ejemplo anterior corresponde a un petición con los datos mínimos
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 una respuesta como la siguiente:
CÓDIGO HTTP: 206
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 Nota Crédito
Nota Adicional
Para la Nota Crédito , es posible aplicar tanto descuentos como recargos generales sin afectar las bases imponibles del documento.
Si desea emitir una nota crédito diferente, puede dirigirse a:
> Nota Crédito a Factura de Venta Nacional
> Nota Crédito a Factura de Salud _ SS-Recaudo
> Nota Crédito a Factura de Salud _ SS-Cufe
> Nota Crédito a Factura de Salud _ SS-Reporte
> Nota Crédito Sin Referencia a Factura
Estamos comprometidos en brindarle una experiencia eficiente y segura en la gestión de sus documentos electrónicos.