Receptor
Clase que contiene todos los atributos del receptor de un documento.
Algunos documentos pueden no tener un receptor.
Propiedad | Descripción |
---|
razon_social | Nombre o razón social de Receptor.
Puede ser el nombre físico de una persona o el nombre de una sociedad anónima.
Por ejemplo: Juan Federico Fernández Hernández.
Tiene un máximo de 80 caracteres. |
identificacion | Contiene los metadatos de la identificación del Receptor
|
identificacion_extranjero | Representa el número de identificación extranjero para un receptor no nacional.
Tiene un máximo de 20 caracteres.
Este campo será de condición obligatoria, cuando el cliente lo requiera.
Normalmente el ente gubernamental exige este dato, si la identificación es de tipo DIMEX, sugerimos enviarlo siempre en ese caso. |
razon_comercial | Nombre de fantasía para el Receptor
En caso de que se cuente con nombre comercial debe indicarse.
Tiene un máximo de 80 caracteres. |
ubicacion | Contiene los metadatos de la ubicación del Receptor. Parámetro Opcional.
|
telefono | Contiene los metadatos del teléfono del Receptor. Parámetro Opcional.
|
fax | Contiene los metadatos del fax del Receptor. Parámetro Opcional.
|
correo_electronico | Correo Electrónico del Receptor
Debe tener formato de correo electrónico válido.
Puede enviar varios correos electrónicos, siempre cuando estén separados por punto y coma (;) y sin espacios. |
Identificacion
Clase que representa la identificación de un Receptor.
Contiene el tipo de identificación y su número.
Propiedad | Descripción |
---|
tipo | Tipo de identificación de acuerdo con la especificación del ente gubernamental.
Los posibles valores y su interpretación son:
01 = Cédula Física
02 = Cédula Jurídica
03 = DIMEX
04 = NITE |
numero | Número de identificación, el contribuyente debe esta inscrito ante la Administración Tributaria
El valor deben oscilar entre 9 y 12 dígitos.
Solo números, no caracteres especiales o letras. |
Ubicacion
Clase que representa datos de ubicación.
Propiedad | Descripción |
---|
provincia | Provincia
Cuando se ingresa este valor, enviar el código de provincia según la lista del ente gubernamental.
Cuando se utilize este objeto de salida, podrá leer el nombre de la provincia completo. |
canton | Cantón
Cuando se ingresa este valor, enviar el código del cantón según la lista del ente gubernamental.
Cuando se utilize este objeto de salida, podrá leer el nombre del cantón completo. |
distrito | Distrito
Cuando se ingresa este valor, enviar el código del distrito según la lista del ente gubernamental.
Cuando se utilize este objeto de salida, podrá leer el nombre del distrito completo. |
barrio | Barrio
Cuando se ingresa este valor, enviar el código del barrio según la lista del ente gubernamental.
Cuando se utilize este objeto de salida, podrá leer el nombre del barrio completo. |
otras_senas | Descripción de la dirección de la ubicación.
Tiene un máximo de 160 caracteres. |
Telefono
Clase que representa un número telefónico.
Propiedad | Descripción |
---|
codigo_pais | Código país del número telefónico.
Valor de 3 dígitos. |
num_telefono | Número telefónico.
Valor máximo de 20 dígitos. |
Fax
Clase que representa un número de fax.
Propiedad | Descripción |
---|
codigo_pais | Código país del número de fax.
Valor de 3 dígitos. |
num_telefono | Número de fax.
Valor máximo de 20 dígitos. |
Clase que representa una referencia a un documento. Se utiliza principalmente en las notas de crédito y débito para reducir el balance de una factura o tiquete.
Propiedad | Descripción |
---|
tipo_doc | Tipo de documento de referencia.
01 = Factura electrónica
02 = Nota de débito electrónica
03 = Nota de crédito electrónica
04 = Tiquete electrónico
05 = Nota de despacho
06 = Contrato
07 = Procedimiento
08 = Comprobante emitido en contingencia
09 = Devolución mercadería
10 = Sustituye factura rechazada por Ministerio de Hacienda
11 = Sustituye factura rechazada por el receptor del comprobante
12 = Sustituye factura de exportación
99 = Otros |
numero | Número de documento de referencia. Es la clave del documento referenciado, por ende se espera un número de 50 caracteres. |
fecha_emision | Fecha y hora de emisión del documento de referencia
El formato es: yyyy-MM-ddTHH:mm:ss |
codigo | Código de referencia. Indica la razón por la cual se hace referencia al documento.
01 = Anula documento de referencia
02 = Corrige texto de documento de referencia
03 = Corrige monto
04 = Referencia a otro documento
05 = Sustituye comprobante provisional por contingencia
99 = Otros |
razon | Razón de referencia, texto abierto que permite indicar una explicación a la razón de referencia.
Máximo de 180 caracteres. |
Detalle Servicio Entrada
Clase que representa el detalle de un documento.
Propiedad | Descripción |
---|
numero_linea | Dígito que representa el número de línea del detalle. Es requerido.
Valor entero. |
tipo_codigo_comercial | Tipo de código del producto. Es requerido.
01 = Código del producto del vendedor
02 = Código del producto del comprador
03 = Código del producto asignado por la industria
04 = Código de uso interno
99 = Otros |
codigo_comercial | Código del producto o servicio en el comercio.
Máximo de 20 caracteres. |
codigo | Código asociado dentro del Catálogo de bienes y servicios (Cabys). Este código se tiene que obtener de una lista oficial que el ente gubernamental publicó.
Limitado a 13 caracteres. Es requerido. |
cantidad | Dígito que representa la cantidad de producto o servicio indicado en este detalle.
Soporta valores con decimales de no mas de 3 decimales, ejemplo: 0.234 |
codigo_moneda | Código o Abreviatura de 3 caracteres que indica la moneda de este detalle. Parámetro OPCIONAL.
Si no se indica, se entiende que la moneda del documento es la misma para este detalle.
Este parámetro permite enviar un detalle con montos en otra moneda y indicar al API FACTUN que convierta el valor.
Ejemplos: 'CRC', 'USD' |
unidad_medida | Unidad de medida del producto o servicio.
Para servicios profesionales siempre enviar 'Sp', por especificación del ente gubernamental.
Ver la lista de unidades de medida del ente gubernamental.
Siempre enviar la abreviatura de la unidad.
Ejemplos: 'Sp', 'mol', 'm/s²', 'Otros' |
unidad_medida_comercial | Unidad de medida comercial. Parámetro OPCIONAL.
Solamente es requerido cuando se especifica unidad de medida 'Otros'.
Valor libre para especificar, pero con un máximo de 20 caracteres. |
detalle | Descripción del producto o servicio
Máximo de 160 caracteres. |
notas | |
registro_medicamento | Se convierte en carácter obligatorio, cuando el código CAByS del producto que se esté comercializando pertenece a un medicamento que posea registro sanitario. |
forma_farmaceutica | Se utilizará para incluir el código de la forma farmacéutica. Al igual que el "registro medicamento" es requerido cuando el CABYS del producto pertenece a un medicamento con registro sanitario. |
precio_unitario | Precio unitario del producto o servicio.
Acepta decimales hasta un máximo de 5.
Valor mínimo: 0
Valor máximo: 9999999999999.99999 |
porcentaje_descuento | Porcentaje de descuento aplicado a esta línea de detalle. Ejemplo para 13%, 13 es el valor válido.
Parámetro OPCIONAL.
Si no se tiene un porcentaje de descuento, pero si un monto descuento, utilizar el parámetro 'monto_impuesto'. |
monto_descuento | Monto unitario del descuento aplicado a esta línea de detalle.
Usar este parámetro cuando no se tenga el porcentaje de descuento.
Si se envía el porcentaje_descuento y el monto_impuesto, el porcentaje_descuento prevalecerá para los cálculos, si es mayor a cero.
El monto debe ser unitario. Acepta decimales hasta un máximo de 5. |
naturaleza_descuento | Descripción de la razón o naturaleza del porque se da el descuento.
Máximo de 80 caracteres.
Ejemplo: 'Oferta de inicio de mes' |
impuesto | Lista o colección de impuestos asociados al detalle.
|
descuento | Nueva opción según Facturación Electrónica 4.3. Corresponde a la lista o colección de descuentos asociados al detalle (hasta 5 descuentos por línea).
IMPORTANTE: Utilizar esta forma solamente si se desea enviar mas de un descuento, de lo contrario por favor utilizar los atributos porcentaje_descuento, monto_descuento y naturaleza_descuento para detallar el descuento
No mesclar los datos enviando un descuento de la forma simple junto con la nueva lista de descuentos
|
iva_devuelto | Valor booleano que indica si se devuelve el IVA del detalle (aplica por ejemplo a servicio médicos pagados con tarjeta).
FALSE = no se devuelve.
TRUE = si se devuelve. |
bonificacion | Valor booleano que indica si a la línea se le debe aplicar la especificación de "bonificacion" ante el ente gubernamental.
FALSE = línea si bonificación
TRUE = línea que se debe bonificar
¿Qué es bonificación? Es cuando un producto o servicio se dá gratis, pero el receptor aun así debe pagar los impuesto correspondientes.
Para poder calcular la bonificación correctamente, los montos deben enviarse como cualquier otra línea de este producto.
En el XML final, el producto tendrá un valor de cero, pero con un impuesto apropiado que suma al gran total del documento. |
partida_arancelaria | Valor que indica la partida arancelaria en facturas de exportación. |
base_imponible | Base para realizar los cálculos de impuestos cuando el código de impuesto es "08"(ventas por catálogo). |
Detalle Servicio Salida
Clase que representa el detalle de un documento.
Propiedad | Descripción |
---|
numero_linea | Dígito que representa el número de línea del detalle.
Se soporta hasta un máximo de 1000 detalles por documento. |
tipo_codigo | Tipo de código del producto.
01 = Código del producto del vendedor
02 = Código del producto del comprador
03 = Código del producto asignado por la industria
04 = Código de uso interno
99 = Otros |
codigo | Código del producto o servicio
Máximo de 20 caracteres |
cantidad | Dígito que representa el cantidad de producto o servicio indicado en este detalle.
Soporta valores con decimales de no mas de 3 decimales, ejemplo: 0.234 |
unidad_medida | Unidad de medida del producto o servicio.
Es la descripción completa de la unidad de medida. |
unidad_medida_comercial | Unidad de medida comercial.
Solamente es requerido cuando se especifica unidad de medida 'Otros'.
Valor libre para especificar, pero con un máximo de 20 caracteres. |
detalle | Descripción del producto o servicio
Máximo de 160 caracteres. |
precio_unitario | Precio unitario del producto o servicio. |
porcentaje_descuento | Porcentaje de descuento aplicado a esta línea de detalle. Ejemplo para 13%, 13 es el valor válido.
Si no se envió un porcentaje inicialmente, pero si un monto descuento, se mostrara un porcentaje calculado por la plataforma Factun. |
monto_descuento | Monto unitario del descuento aplicado a esta línea de detalle. |
naturaleza_descuento | Descripción de la razón o naturaleza del porque se da el descuento.
Máximo de 80 caracteres.
Ejemplo: 'Oferta de inicio de mes' |
impuesto | Lista o colección de impuestos asociados al detalle.
|
subtotal_linea | Subtotal de la linea (sin descuento y sin impuesto) |
total_descuento_linea | Monto Total del Descuento (no unitario) |
total_impuesto_linea | Monto Total del Impuesto (no unitario) |
total_linea | Monto Total (no unitario) de todo el valor de la linea |
servicio | Valor booleano que indica si el detalle es un servicio profesional o no.
FALSE = linea es un producto.
TRUE = linea es un servicio profesional |
bonificacion | Valor booleano que indica si a la linea se le ha aplicado la especificación de "bonificacion" ante el ente gubernamental.
FALSE = linea sin bonificación
TRUE = linea que se debe bonificar
Puede ver mas información acerca de bonificación en Detalle Servicio Entrada |
Resumen Documento Entrada
Clase que contiene más atributos que describen el documento así como su contexto.
Propiedad | Descripción |
---|
codigo_moneda | Código o Abreviatura de 3 caracteres que indica la moneda del documento. Parámetro REQUERIDO.
Ejemplos: 'CRC', 'USD' |
tipo_cambio | Tipo de cambio de la moneda con respecto al COLON Costarricense.
Acepta decimales hasta un máximo de 2.
Si este parámetro no se indica, el tipo de cambio se obtendrá de la configuración de Factun para la sucursal de este documento. |
Resumen Documento Salida
Clase que contiene mas atributos que describen el documento así como su contexto.
Propiedad | Descripción |
---|
codigo_moneda | Código o Abreviatura de 3 caracteres que indica la moneda del documento.
Ejemplos: 'CRC', 'USD' |
tipo_cambio | Tipo de cambio de la moneda con respecto al COLON Costarricense. |
total_comprobante | Monto Total del documento |
total_impuesto | Monto Total de los impuesto gravados |
total_descuento | Monto Total del descuento aplicado al documento |
Impuesto Entrada
Clase que representa un impuesto específico asociado a una línea de detalle
Propiedad | Descripción |
---|
codigo | Código del impuesto.
Al utilizar el código 07 se debe de utilizar para el cálculo del impuesto el campo denominado "base imponible" y la tarifa (ventas por catálogo).
Al utilizar el código 08, se debe utilizar para el cálculo de factor del IVA por el subtotal.
01 = Impuesto al Valor Agregado
02 = Impuesto Selectivo de Consumo
03 = Impuesto único a los combustibles
04 = Impuesto específico de bebidas alcohólicas
05 = Impuesto específico sobre las bebidas envasadas sin contenido alcohólico y jabones de tocador
06 = Impuesto a los productos de tabaco
07 = IVA (cálculo especial)
08 = IVA Régimen de Bienes Usados (Factor)
12 = Impuesto Especifico al cemento
99 = Otros |
tarifa | Porcentaje del Impuesto
Ejemplo 13.00 significa 13% |
codigo_tarifa | Código de la tarifa del Impuesto. Se convierte en obligatorio para los Códigos 01, 07.
01 = Tarifa 0% (Exento)
02 = Tarifa Reducida 1%
03 = Tarifa reducida 2%
04 = Tarifa reducida 4%
05 = Transitorio 0%
06 = Transitorio 4%
07 = Transitorio 8%
08 = Tarifa General 13% |
factor_iva | Factor del IVA
Cuando en el código de impuesto se defina IVA Bienes Usados (08) se deberá utilizar este campo con el factor establecido por el Ministerio de Hacienda. |
exoneracion | Contiene los metadatos de la exoneración que aplica al impuesto
|
Impuesto Salida
Clase que representa un impuesto específico asociado a una línea de detalle
Esta clase es diferente de la clase Impuesto Entrada, ya que puede contener mas propiedades descriptivas.
Propiedad | Descripción |
---|
codigo | Código del impuesto
01 = Impuesto General sobre las ventas
02 = Impuesto Selectivo de Consumo
03 = Impuesto único a los combustibles
04 = Impuesto específico de bebidas alcohólicas
05 = Impuesto específico sobre las bebidas envasadas sin contenido alcohólico y jabones de tocador
06 = Impuesto a los productos de tabaco
07 = Servicios
99 = Otros
08 = Impuesto General a las Ventas Diplomáticos
09 = Impuesto General sobre Ventas compras autorizadas
10 = Impuesto General sobre las ventas instituciones públicas y otros organismos
11 = Impuesto Selectivo de consumo compras autorizadas
12 = Impuesto Especifico al cemento
98 = Otros |
tarifa | Porcentaje del Impuesto
Ejemplo 13.00 significa 13%
Puede verse reducido si se compara con el parámetro de entrada debido a una exoneración, API FACTUN hace la reducción automáticamente. |
monto_impuesto | Monto Unitario del impuesto gravado al detalle correspondiente |
exoneracion | Contiene los metadatos de la exoneración que aplica al impuesto
|
Descuento Entrada
Propiedad | Descripción |
---|
porcentaje_descuento | Porcentaje de descuento aplicado a esta línea de detalle. Ejemplo para 13%, 13 es el valor válido.
Parámetro OPCIONAL.
Si no se tiene un porcentaje de descuento, pero si un monto descuento, utilizar el parámetro 'monto_impuesto'. |
monto_descuento | Monto del descuento aplicado a esta línea de detalle.
Usar este parámetro cuando no se tenga el porcentaje de descuento.
Si se envía el porcentaje_descuento y el monto_impuesto, el porcentaje_descuento prevalecerá para los cálculos, si es mayor a cero.
El monto debe ser unitario. |
naturaleza_descuento | Descripción de la razón o naturaleza del porque se da el descuento.
Máximo de 80 caracteres.
Ejemplo: 'Oferta de inicio de mes' |
Exoneración Entrada
Clase que representa una exoneración a un impuesto
Propiedad | Descripción |
---|
tipo_documento | Tipo de documento de exoneración o autorización.
01 = Compras Autorizadas
02 = Ventas exentas a diplomáticos
03 = Orden de compra(instituciones públicas y otros organismos)
04 = Exenciones Dirección General de Hacienda
05 = Transitorio V
06 = Transitorio IX
07 = Transitorio XVII
99 = Otros |
numero_documento | Número de documento de exoneración o autorización
Máximo de 17 caracteres |
nombre_institucion | Nombre de la institución o dependencia que emitió la exoneración
Máximo 100 caracteres |
fecha_emision | Fecha y hora de la emisión del documento de exoneración o autorización
El formato es: yyyy-MM-ddTHH:mm:ss |
porcentaje_exoneracion | Porcentaje de la compra autorizada o exonerada
Ejemplo, si el impuesto es del 13% y se desea aplicar un 100% de exoneración del porcentaje del impuesto
se debe colocar 13 en este campo según la estipulación de hacienda |
Exoneración Salida
Clase que representa una exoneración a un impuesto.
Esta clase es diferente de la clase Exoneración Entrada, ya que puede contener mas propiedades descriptivas.
Propiedad | Descripción |
---|
tipo_documento | Tipo de documento de exoneración o autorización.
01 = Compras Autorizadas
02 = Ventas exentas a diplomáticos
03 = Orden de compra(instituciones públicas y otros organismos)
04 = Exenciones Dirección General de Hacienda
05 = Zonas Francas
99 = Otros |
numero_documento | Número de documento de exoneración o autorización
Máximo de 17 caracteres |
nombre_institucion | Nombre de la institución o dependencia que emitió la exoneración
Máximo 100 caracteres |
fecha_emision | >Fecha y hora de la emisión del documento de exoneración o autorización
El formato es: yyyy-MM-ddTHH:mm:ss |
porcentaje_exoneracion | Porcentaje de la compra autorizada o exonerada
Ejemplo, si el impuesto es del 13% y se desea aplicar un 100% de exoneración del porcentaje del impuesto
se debe colocar 13 en este campo según la estipulación de hacienda |
monto_exoneracion | Monto unitario de la exoneracion aplicada al impuesto asociado |
Otro Contenido Entrada
Representa otro contenido en el campo otros del XML de un documento.
Propiedad | Descripción |
---|
Codigo | Código alfanumérico del otro contenido.
Ejemplo: "NumeroOrden" |
Valor | Valor alfanumérico del otro contenido.
Ejemplo: "254199" |
Otro Cargo Entrada
Clase que representa la información de otros cargos en el documento.
Máximo 15 otros cargos.
Propiedad | Descripción |
---|
tipo_documento | Especifica el tipo de documento del cargo
01 = Contribución parafiscal
02 = Timbre de la Cruz Roja
03 = Timbre de Benemérito Cuerpo de Bomberos de Costa Rica
04 = Cobro de un tercero
05 = Costos de Exportación
06 = Impuesto de Servicio 10%
07 = Timbre de Colegios Profesionales
99 = Otros Cargos |
numero_identidad_tercero | Número de cédula física/jurídica/NITE/DIMEX del tercero.
Máximo de 12 caracteres. |
nombre_tercero | Nombre o razón social del tercero.
Máximo de 100 caracteres. |
detalle | Descripción del cargo.
Máximo de 160 caracteres. |
porcentaje | Porcentaje del cargo. |
monto_cargo | Monto del cargo. |