Todos los datos transferidos a través del HTTP BODY deben ser en formato JSON. El API FACTUN siempre responderá en formato JSON todos los datos que retorne en el HTTP BODY.
Error Interno: cuando ocurre una excepción no manejada, el API responderá con un HTTP CODE 500 (Internal Server Error) y normalmente adjunta un mensaje como el siguiente:
Ha ocurrido un error interno, por favor reintentar o contactar con Factun si el error persiste. Error: Nullable object must have a value.
Flujo API FACTUN
El API tiene 7 métodos para documentos, aunque no es necesario invocar todos. A continuación se muestra la lógica a seguir dependiendo del estado del documento:
-
POST Documento/Procesar (se crea la recepción y se envía al ente gubernamental en un solo paso)
-
Si estado_hacienda es igual a ENVIADO (04)
- El documento se encuentra bien, puede continuar con la llamada a consultar.
-
Si estado_hacienda es igual a NO ENVIADO (05)
- El documento no se encuentra en el ente gubernamental, debe utilizar la llamada PUT Documento/Reenviar hasta lograr obtener un ENVIADO (04)
-
PUT Documento/Consultar (consultar la respuesta del ente gubernamental y notifica si usted tiene habilitada la opción de notificación automática para su API USER)
-
Si estado_hacienda es igual a ACEPTADO (01), ACEPTADO PARCIALMENTE (02) o RECHAZADO (03)
- El documento tiene una resolución final, no hay mas acciones de modificación al documento
-
Si estado_hacienda es diferente
- El documento NO tiene una resolución final, puede seguir usando PUT Documento/Consultar hasta obtener una resolución definitiva.
-
Llamadas opcionales:
-
Si desea obtener más detalles del documento y confirmar todos los datos, puede utilizar GET Documento.
-
Si desea descargar el XML generado, puede utilizar GET Documento/XML.
-
Si desea descargar el XML de respuesta del ente gubernamental, puede utilizar GET Documento/RespuestaXML.
-
Si desea notificar manualmente o reenviar el documento a otros correos electrónicos, puede utilizar POST Documento/Notificar.
El API tiene 5 métodos para recepción. No es necesario invocar todos los métodos. A continuación se muestra la lógica a seguir dependiendo del estado de la recepción:
-
POST Recepcion/Enviar (se crea la recepción y se envía al ente gubernamental en un solo paso).
-
Si estado_hacienda es igual a ENVIADO (04).
- La recepción se encuentra bien, puede continuar con la llamada a consultar.
-
Si estado_hacienda es igual a NO ENVIADO (05).
- La recepción no se encuentra en el ente gubernamental, debe utilizar la llamada PUT Recepcion/Reenviar hasta lograr obtener un ENVIADO (04).
-
PUT Recepcion/Consultar (consultar la respuesta del ente gubernamental)
-
Si estado_hacienda es igual a ACEPTADO (01), ACEPTADO PARCIALMENTE (02) o RECHAZADO (03)
- La recepción tiene una resolución final, no hay mas acciones de modificación a la recepción.
-
Si estado_hacienda es diferente
- La recepción NO tiene una resolución final, puede seguir usando PUT Consultar hasta obtener una resolución final.
-
Llamadas opcionales:
-
Si desea descargar el XML generado, puede utilizar GET Recepcion/XML
-
Si desea descargar el XML de respuesta del ente gubernamental, puede utilizar GET Recepcion/RespuestaXML.
Estándar de respuesta API FACTUN
API FACTUN responde casi todos sus métodos serializando la clase Resultado. Esta clase es de enfoque genérico y se usa para informar el resultado casi todas las transacciones.
La clase Resultado almacena datos y mensajes (éxito y error).
Puede observar la clase Resultado en código c#:
public class Resultado
{
public bool exito { get; set; } //Indica si la transacción o acción se considera completamente exitosa o no
public int id { get; set; } //Cuando se trabaja con recursos, indica el identificador interno del recurso en la plataforma Factun
public Dictionary< string, string> data { get; set; } //Diccionario string key|value donde se devuelven datos.
public Dictionary< string, string> mensajes { get; set; } //Diccionario string key|value donde se devuelven únicamente mensajes y códigos de mensaje.
public Resultado()
{
this.data = new Dictionary< string, string>();
this.mensajes = new Dictionary< string, string>();
}
}
Estado Hacienda
La propiedad data de muchos métodos incluye un valor llamado "estado_hacienda", la siguiente lista le ayudara a interpretar los valores de "estado_hacienda":
- 00: Pendiente, el documento ha sido creado, pero no se realizado ningún intento o acción de envío al ente gubernamental.
- 01: Aceptado, el documento se encuentra aceptado por el ente gubernamental. Es una resolución final.
- 02: Aceptado parcialmente, el documento fue aceptado parcialmente por el ente gubernamental. Es una resolución final
- 03: Rechazado, el documento fue rechazado por el ente gubernamental normalmente debido a algún error en el xml enviado. Es una resolución final
- 04: Enviado, el documento fue enviado al ente gubernamental, pero no sea consultado al ente gubernamental acerca de una resolución del documento.
- 05: No Enviado, el documento no pudo ser enviado al ente gubernamental, normalmente por algún error de comunicación, el envío se puede reintentar usando el mismo documento, no es aconsejable crear otro documento.
- 07: Recibido, el documento fue recibido por el ente gubernamental pero todavía no se ha emitido una resolución final.
- 08: Procesando, el ente gubernamental informa que todavía está procesando la resolución final del documento.
- 09: Enviando, el documento se encuentra dentro del proceso asíncrono de envío, todavía no ha sido enviado al ente gubernamental. En poco tiempo cambiará automáticamente a "ENVIADO" (04).
Descripción
Permite obtener la información completa de un documento a partir de la clave del mismo.
HTTP METHOD: GET
URL de pruebas: https://dev.api.factun.com/api/V2/Documento/{clave}
URL de producción: https://api.factun.com/api/V2/Documento/{clave}
Parámetros
{clave}: El único parámetro aceptado. Debe ser enviada en el URL. Representa la clave numérica de 50 caracteres asociada al documento.
Respuestas
-
HTTP STATUS 404: Not Found: La clave especificada no existe.
Deberá revisar que su clave esté completa y es correcta.
-
HTTP STATUS 401: Unauthorized: Credenciales invalidas para la sucursal del documento.
Deberá revisar que la clave sea de un documento que esté dentro del contexto correcto, o sea, que corresponda a la sucursal y compañía a la cual el token representa.
Nadie debería intentar acceder a documentos que no le pertenecen.
-
HTTP STATUS 200: OK: La llamada ha sido completada.
La salida será un objeto JSON que representa al documento. Puede revisar la documentación del objeto aquí (Documento JSON Salida)
A continuación se muestra un ejemplo de una respuesta:
{
"numero_original": "123456",
"tipo_documento": "01",
"clave": "50616011900310137293500100001010000000456127254151",
"estado_hacienda": "01 - Aceptado",
"consecutivo": "456",
"fecha_emision": "2019-01-16T03:52:00",
"condicion_venta": "02",
"numero_factura": "00100001010000000456",
"plazo_credito": "23",
"medio_pago": [
"01"
],
"receptor": {
"razon_social": "Un cliente",
"identificacion": {
"tipo": "01",
"numero": "206380096"
},
"identificacion_extranjero": null,
"razon_comercial": "Ubitec",
"ubicacion": {
"provincia": "Alajuela",
"canton": "Alajuela",
"distrito": "ALAJUELA",
"barrio": "Acequia Grande (parte)",
"otras_senas": "Barrio San Roque"
},
"telefono": {
"codigo_pais": "506",
"num_telefono": "85688785"
},
"fax": null,
"correo_electronico": "fedex@tucorreo.cr;oscar@tucorreo.cr"
},
"detalle_servicio": [
{
"numero_linea": 1,
"tipo_codigo": "01",
"codigo": "PROD-02",
"cantidad": 7,
"unidad_medida": "Unidad",
"detalle": "Impresora Epson",
"precio_unitario": 47500,
"porcentaje_descuento": 4.21053,
"monto_descuento": 2000,
"naturaleza_descuento": "Oferta",
"impuesto": [
{
"codigo": "07",
"tarifa": 6.5,
"monto_impuesto": 2957.5,
"exoneracion": {
"tipo_documento": "01",
"numero_documento": "2525",
"nombre_institucion": "Institución",
"fecha_emision": "2018-07-02T00:00:00",
"porcentaje_exoneracion": 6.5,
"monto_exoneracion": 2957.5
}
}
],
"subtotal_linea": 332500,
"total_descuento_linea": 14000,
"total_impuesto_linea": 20702.5,
"total_linea": 339202.5,
"servicio": true,
"bonificacion": false
}
],
"resumen_documento": {
"codigo_moneda": "CRC",
"tipo_cambio": 578,
"total_comprobante": 339202.5,
"total_impuesto": 20702.5,
"total_descuento": 14000
},
"informacion_referencia": [],
"exito": true,
"mensaje": "El documento fue obtenido exitosamente."
}
Descripción
Permite crear un documento. El documento se envía al ente gubernamental inmediatamente.
Esta es la llamada principal y el método de inicio. Sin documentos, no se puede realizar ninguna de las otras acciones.
Al utilizar esta llamada y otras, siempre este atento al estado_hacienda del documento, la interpretación de ese valor indica que hacer y que no hacer.
HTTP METHOD: POST
URL de pruebas: https://dev.api.factun.com/api/V2/Documento/Enviar
URL de producción: https://api.factun.com/api/V2/Documento/Enviar
Parámetros
DocumentoJSON: Objeto JSON con todos los metadatos del documento. Este JSON debe estar presente en el HTTP BODY.
Puede revisar la documentación del objeto aqui (Documento JSON Entrada)
A continuación se muestra un ejemplo del objeto JSON de entrada:
{
"id_externo": "123456",
"tipo_documento": "01",
"codigo_actividad": "721001",
"fecha_emision": "2022-02-24T11:30:00",
"receptor":{
"razon_social": "Juan Federico Gonzalez",
"identificacion":{
"tipo": "01",
"numero":"206380095"
},
"identificacion_extranjero": null,
"razon_comercial": "Juan",
"ubicacion": {
"provincia": "2",
"canton": "01",
"distrito": "01",
"barrio": "01",
"otras_senas": "Barrio San Roque 50 metros norte de la Escuela Juan Bautista"
},
"telefono": {
"codigo_pais": "506",
"num_telefono": "85688785"
},
"fax": null,
"correo_electronico": "federico@compania.co.cr;amigos@compania.co.cr"
},
"condicion_venta": "02",
"plazo_credito": "23",
"medio_pago": ["01"],
"detalles":[
{
"numero_linea": 1,
"codigo": "4526300000000",
"cantidad": 2,
"unidad_medida": "Unid",
"unidad_medida_comercial": null,
"tipo_codigo_comercial": "04",
"codigo_comercial": "IMP-02",
"detalle": "Impresora Epson",
"precio_unitario": 47500,
"monto_descuento": 2000,
"naturaleza_descuento": "Oferta",
"impuesto": [{
"codigo": "01",
"tarifa": 13,
"codigo_tarifa": "08",
"exoneracion": {
"tipo_documento":"04",
"numero_documento":"AL-00008244-22",
"nombre_institucion": "Dirección General de Hacienda",
"fecha_emision":"2022-02-11T00:00:00",
"porcentaje_exoneracion": 13
}
}],
"bonificacion":false
}],
"resumen_documento": {
"codigo_moneda": "CRC",
"tipo_cambio": 640
}
}
Respuestas
-
HTTP STATUS 404: Not Found: La clave especificada no existe.
Deberá revisar que su clave está completa y es correcta.
-
HTTP STATUS 401: Unauthorized: Credenciales invalidas para la sucursal del documento.
Deberá revisar que la clave sea de un documento que esté dentro del contexto correcto, o sea, que corresponsa a la sucursal y compania a la cual el token representa.
Nadie debería intentar acceder a documentos que no le pertenecen.
-
HTTP STATUS 200: OK: La llamada ha sido completada.
La salida será un objeto JSON que representa el estado de la transacción y del documento.
A continuación se muestra un ejemplo de una respuesta exitosa:
{
"exito": true,
"id": 97683,
"data": {
"consecutivo": "4",
"clave": "50624022200310137293500100001010000000692111651298",
"numero_factura": "00100001010000000692",
"estado_hacienda": "04",
"moneda": "CRC",
"total_comprobante": "97519"
},
"mensajes": {}
}
Interpretacion del atributo data:
- consecutivo: Representa el número de consecutivo que se encuentra en la clave del documento. Este número es el consecutivo directo sin ceros a la izquierda.
- clave: Representa la clave electrónica del documento. Tiene un tamaño de 50 caracteres.
- numero_factura: Representa el número de documento que se encuentra en la clave del documento. Este número es de 20 caracteres y para el ente gubernamental es el número de consecutivo en el XML.
- estado_hacienda: Representa los diferentes estados de la recepción en la Factun. Estos estados reflejan su situation ante el ente gubernamental.
- moneda: Abreviatura de la moneda del documento.
- total_comprobante: Cantidad final y total del documento, valor calculado por la plataforma de Factun con 5 decimales.
Errores de Validación
Pueden presentarse errores en los parámetros de entrada que generen el código de error "06-A" (usted recibirá una lista de atributos "param_[key]")
A continuación se muestra un ejemplo de una respuesta que indica que se detectaron errores de parámetros:
{
"exito": false,
"id": 0,
"data": {},
"mensajes": {
"param_clave": "La clave del comprobante debe contener 50 caracteres.",
"param_tipo_documento": "El tipo de documento no se puede reconocer.",
"codigo_mensaje": "06-A",
"mensaje": "Documento presenta errores",
"detalle_mensaje": "Existen errores de validación inicial del documento y debe revisarse los parámetros de entrada de DocumentoJSON Entrada. Puede revisar los atributos param_[key] en la lista de mensajes."
}
}
Descripción
Permite crear un documento exactamente igual al método enviar, la diferencia es que el documento se envía al ente gubernamental NO inmediatamente, sino de manera asíncrona.
Al utilizar esta llamada y otras, siempre este atento al estado_hacienda del documento, la interpretación de ese valor indica que hacer y que no hacer.
HTTP METHOD: POST
URL de pruebas: https://dev.api.factun.com/api/V2/Documento/EnviarAsync
URL de producción: https://api.factun.com/api/V2/Documento/EnviarAsync
Descripción
Permite consultar el estado (respuesta) del ente gubernamental al documento y guardar la respuesta para el documento.
HTTP METHOD: PUT
URL de pruebas: https://dev.api.factun.com/api/V2/Documento/Consultar/{clave}
URL de producción: https://api.factun.com/api/V2/Documento/Consultar/{clave}
Parámetros
{clave}: El único parámetro aceptado. Debe ser enviada en el URL. Representa la clave numérica de 50 caracteres asociada al documento.
Respuestas
-
HTTP STATUS 404: Not Found: La clave especificada no existe.
Deberá revisar que su clave está completa y es correcta.
-
HTTP STATUS 401: Unauthorized: Credenciales invalidas para la sucursal del documento.
Deberá revisar que la clave sea de un documento que esté dentro del contexto correcto, o sea, que corresponda a la sucursal y compañía a la cual el token representa.
Nadie debería intentar acceder a documentos que no le pertenecen.
-
HTTP STATUS 200: OK: La llamada ha sido completada.
La salida será un objeto JSON que representa el estado de la transacción y del documento.
A continuación se muestra un ejemplo de una respuesta completamente exitosa con resolución RECHAZADO:
{
"exito": true,
"id": 97684,
"data": {
"clave": "50611011900310137293500100001010000000453116322411",
"detalle": "Este comprobante fue aceptado en el ambiente de pruebas, por lo cual no tiene validez para fines tributarios\n\nEl comprobante electrónico tiene los siguientes errores: \n\n[\ncodigo, mensaje, fila, columna\n-1, \"cvc-complex-type.2.4.a: Invalid content was found starting with element 'DetalleServicio'. One of '{\"https://tribunet.hacienda.go.cr/docs/esquemas/2017/v4.2/facturaElectronica\":MedioPago}' is expected.\", 44, 20\n\n]",
"resolucion": "RECHAZADO",
"estado_hacienda": "03",
"consecutivo": "453",
"numero_documento": "00100001010000000453"
},
"mensajes": {}
}
A continuación se muestra una ejemplo de una respuesta completada exitosamente y con resolución ACEPTADO:
{
"exito": true,
"id": 97685,
"data": {
"clave": "50611011900310137293500100001010000000454116322411",
"detalle": "Este comprobante fue aceptado en el ambiente de pruebas, por lo cual no tiene validez para fines tributarios\n\ncodigo, mensaje, fila, columna\n-53, \"La hora indicada en la emisión del archivo XML no coincide con la hora oficial.\", 0, 0\n-37, \"Estimado obligado tributario los datos suministrados en provincia, cantón y distrito del 'emisor' no concuerdan con la información registrada en la Dirección General de Tributación, favor proceder actualizar sus datos.\", 0, 0\n",
"resolucion": "ACEPTADO",
"estado_hacienda": "01",
"consecutivo": "454",
"numero_documento": "00100001010000000454"
},
"mensajes": {}
}
A continuación se muestra una ejemplo de una respuesta completada pero hubo un error, ya que el documento no ha sido enviado aun:
{
"exito": false,
"id": 88108,
"data": {
"clave": "50618071800310137293500100001010000000311135165178",
"detalle": "No se pudo obtener resolución debio a error. El comprobante [50618071800310137293500100001010000000311135165178] no ha sido recibido.",
"resolucion": "No se pudo obtener el estado",
"estado_hacienda": "04",
"consecutivo": "311",
"numero_documento": "00100001010000000311"
},
"mensajes": {
"detalle_mensaje": "El comprobante [50618071800310137293500100001010000000311135165178] no ha sido recibido.",
"mensaje": "El ente gubernamental informa un error",
"codigo_mensaje": "03"
}
}
Descripción
Permite consultar el estado del documento dentro del proceso automático (para documentos creados por EnviarAsync).
HTTP METHOD: PUT
URL de pruebas: https://dev.api.factun.com/api/V2/Documento/ConsultarAsync/{clave}
URL de producción: https://api.factun.com/api/V2/Documento/ConsultarAsync/{clave}
Parámetros
{clave}: El único parámetro aceptado. Debe ser enviada en el URL. Representa la clave numérica de 50 caracteres asociada al documento.
Respuestas
-
HTTP STATUS 404: Not Found: La clave especificada no existe.
Deberá revisar que su clave está completa y es correcta.
-
HTTP STATUS 401: Unauthorized: Credenciales invalidas para la sucursal del documento.
Deberá revisar que la clave sea de un documento que esté dentro del contexto correcto, o sea, que corresponda a la sucursal y compañía a la cual el token representa.
Nadie debería intentar acceder a documentos que no le pertenecen.
-
HTTP STATUS 200: OK: La llamada ha sido completada.
La salida será un objeto JSON que representa el estado de la transacción y del documento.
A diferencia del método normal de Consultar, este no realiza un llamado o Request a hacienda, si no que retorna el estado actual del documento en el proceso asíncrono de envio y consulta.
A continuación se muestra un ejemplo de una respuesta exitosa cuando el documento se está enviando:
{
"exito": true,
"id": 97684,
"data": {
"clave": "50620091900310137293500100001010000000453116322411",
"estado_hacienda": "09",
"consecutivo": "453",
"numero_documento": "00100001010000000453"
},
"mensajes": {
"detalle_mensaje": "Por favor, espere, el proceso automático esta enviando el documento."}
}
A continuación se muestra una ejemplo de una respuesta exitosa cuando el documento ya fué enviado:
{
"exito": true,
"id": 97684,
"data": {
"clave": "50620091900310137293500100001010000000453116322411",
"estado_hacienda": "04",
"consecutivo": "453",
"numero_documento": "00100001010000000453"
},
"mensajes": {
"detalle_mensaje": "Por favor, espere, el proceso automático esta consultando el documento."}
}
A continuación se muestra una ejemplo de una respuesta exitosa y con resolución ACEPTADO:
{
"exito": true,
"id": 97685,
"data": {
"clave": "50611011900310137293500100001010000000454116322411",
"detalle": "Este comprobante fue aceptado en el ambiente de pruebas, por lo cual no tiene validez para fines tributarios\n\ncodigo, mensaje, fila, columna\n-53, \"La hora indicada en la emisión del archivo XML no coincide con la hora oficial.\", 0, 0\n-37, \"Estimado obligado tributario los datos suministrados en provincia, cantón y distrito del 'emisor' no concuerdan con la información registrada en la Dirección General de Tributación, favor proceder actualizar sus datos.\", 0, 0\n",
"resolucion": "ACEPTADO",
"estado_hacienda": "01",
"consecutivo": "454",
"numero_documento": "00100001010000000454"
},
"mensajes": {
"detalle_mensaje" : "Consulta de documento exitosa."
}
}
Descripción
Permite reenviar un documento al ente gubernamental cuando el método regular de enviar notifica un error y retorna el documento como NO ENVIADO (05).
HTTP METHOD: PUT
URL de pruebas: https://dev.api.factun.com/api/V2/Documento/Reenviar/{clave}
URL de producción: https://api.factun.com/api/V2/Documento/Reenviar/{clave}
Parámetros
{clave}: El único parámetro aceptado. Debe ser enviada en el URL. Representa la clave numérica de 50 caracteres asociada al documento.
Respuestas
-
HTTP STATUS 404: Not Found: La clave especificada no existe.
Deberá revisar que su clave está completa y es correcta.
-
HTTP STATUS 401: Unauthorized: Credenciales invalidas para la sucursal del documento.
Deberá revisar que la clave sea de un documento que esté dentro del contexto correcto, o sea, que corresponda a la sucursal y compania a la cual el token representa.
Nadie debería intentar acceder a documentos que no le pertenecen.
-
HTTP STATUS 200: OK: La llamada ha sido completada.
La salida será un objeto JSON que representa el estado de la transacción y del documento.
A continuación se muestra un ejemplo de una respuesta exitosa, este método retorna la misma respuesta que el enviar:
{
"exito": true,
"id": 97686,
"data": {
"consecutivo": "455",
"clave": "50611011900310137293500100001010000000455116322411",
"numero_factura": "00100001010000000455",
"moneda": "CRC",
"total_comprobante": "339202.50000",
"estado_hacienda": "04"
}
}
A continuación se muestra un ejemplo de una respuesta no exitosa, porque se trato de reenviar un documento que ya estaba enviado:
{
"exito": false,
"id": 97686,
"data": {
"consecutivo": "455",
"clave": "50611011900310137293500100001010000000455116322411",
"numero_factura": "00100001010000000455",
"moneda": "CRC",
"total_comprobante": "339202.50000",
"estado_hacienda": "04"
},
"mensajes": {
"detalle_mensaje": "El documento con la clave 50611011900310137293500100001010000000455116322411 ya fue enviado al ente gubernamental.",
"mensaje": "Peticion Duplicada",
"codigo_mensaje": "07"
}
}
Descripción
Permite reenviar un documento al ente gubernamental cuando el método regular de enviar notifica un error y retorna el documento como NO ENVIADO (05).
Se hace el reenvío por medio del sistema asíncrono.
HTTP METHOD: PUT
URL de pruebas: https://dev.api.factun.com/api/V2/Documento/ReenviarAsync/{clave}
URL de producción: https://api.factun.com/api/V2/Documento/ReenviarAsync/{clave}
Descripción
Permite reenviar una notificación de correo para un documento, ya sea a toda la lista original mas otros destinarios o solamente a unos nuevos destinarios.
La notificación es un correo electrónico de info@factun.com que informa acerca de la creación del documento y adjunta los 3 archivos esperados: 1 pdf del documento, 1 xml que representa el documento, 1 xml de la respuesta del ente gubernamental.
HTTP METHOD: POST
URL de pruebas: https://dev.api.factun.com/api/V2/Documento/Notificar
URL de producción: https://api.factun.com/api/V2/Documento/Notificar
Parámetros
DocumentoJSON: Objeto JSON con todos los metadatos del documento. Este JSON debe estar presente en el HTTP BODY.
Puede revisar la documentación del objeto aqui (Notificacion JSON Entrada)
A continuación se muestra un ejemplo del objeto JSON de entrada:
{
"resolucion" : 1,
"detalle" : "yo acepto este documento",
"clave_recepcion": "50620071800310137293500100001050000000006110694040",
"xml": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTg..."
}
Errores de validación
Destinario es requerido. Debe indicar los correos separados por punto y coma(;). Esto aplica cuando "nuevo_envio" es TRUE.
Destinarios incorrectos o inválidos. Solamente se aceptan correos electrónicos válidos separados por punto y coma (;). Evite espacios en la cadena.
Respuestas
-
HTTP STATUS 404: Not Found: La clave especificada no existe.
Deberá revisar que su clave está completa y es correcta.
-
HTTP STATUS 401: Unauthorized: Credenciales invalidas para la sucursal del documento.
Deberá revisar que la clave sea de un documento que esté dentro del contexto correcto, o sea, que corresponda a la sucursal y compania a la cual el token representa.
Nadie debería intentar acceder a documentos que no le pertenecen.
-
HTTP STATUS 200: OK: La llamada ha sido completada.
La salida será un objeto JSON que representa el estado de la transacción y del documento.
A continuación se muestra un ejemplo de una respuesta:
{
"exito": true,
"id": 4025,
"data": {},
"mensajes": {}
}
A continuación se muestra un ejemplo de una respuesta NO exitosa:
{
"exito": false,
"id": 0,
"data": {},
"mensajes": {
"detalle_mensaje": "Debe indicar los correos separados por punto y coma(;).",
"mensaje": "Destinario es requerido",
"codigo_mensaje": "15"
}
}
Descripción
Permite obtener el XML creado por Factun utilizando la clave del documento.
HTTP METHOD: GET
URL de pruebas: https://dev.api.factun.com/api/V2/Documento/XML/{clave}
URL de producción: https://api.factun.com/api/V2/Documento/XML/{clave}
Parámetros
{clave}: El único parámetro aceptado. Debe ser enviada en el URL. Representa la clave numérica de 50 caracteres asociada al documento.
Respuestas
-
HTTP STATUS 404: Not Found: La clave especificada no existe.
Deberá revisar que su clave está completa y es correcta.
-
HTTP STATUS 401: Unauthorized: Credenciales invalidas para la sucursal del documento.
Deberá revisar que la clave sea de un documento que esté dentro del contexto correcto, o sea, que corresponda a la sucursal y compania a la cual el token representa.
Nadie debería intentar acceder a documentos que no le pertenecen.
-
HTTP STATUS 200: OK: La llamada ha sido completada.
La salida será un xml plano.
Observe un ejemplo del contenido en RESPONSE BODY de la llamada:
Descripción
Permite obtener el XML de respuesta del ente gubernamental utilizando la clave del documento.
HTTP METHOD: GET
URL de pruebas: https://dev.api.factun.com/api/V2/Documento/RespuestaXML/{clave}
URL de producción: https://api.factun.com/api/V2/Documento/RespuestaXML/{clave}
Parámetros
{clave}: El único parámetro aceptado. Debe ser enviada en el URL. Representa la clave numérica de 50 caracteres asociada al documento.
Respuestas
-
HTTP STATUS 404: Not Found: La clave especificada no existe.
Deberá revisar que su clave está completa y es correcta.
-
HTTP STATUS 401: Unauthorized: Credenciales invalidas para la sucursal del documento.
Deberá revisar que la clave sea de un documento que esté dentro del contexto correcto, o sea, que corresponda a la sucursal y compania a la cual el token representa.
Nadie debería intentar acceder a documentos que no le pertenecen.
-
HTTP STATUS 200: OK: La llamada ha sido completada.
La salida será un xml plano.
Observe un ejemplo del contenido en RESPONSE BODY de la llamada:
Descripción
Las correos electrónicos con xml que se envían para que su compañía realice una recepción, pueden reenviarse a recepcion@factun.com, estos los conocemos como recepciones del buzón o borradores
Permite obtener la lista actualizada de los borradores recibidos PENDIENTES DE ACCION (esto es que no han sido actualizados como Importados o Descartados) en el buzón de recepciones que aplican para la compania a la cual el token representa.
HTTP METHOD: GET
URL de pruebas: https://dev.api.factun.com/api/V2/Recepcion/Borradores
URL de producción: https://api.factun.com/api/V2/Recepcion/Borradores
Parámetros
Sin parámetros
Respuestas
-
HTTP STATUS 200: OK: La llamada ha sido completada.
La salida será un objeto JSON que representa una lista de borradores.
Puede revisar la documentación del objeto aquí (RecepcionBorradorLista JSON Salida)
A continuación se muestra un ejemplo de una respuesta exitosa:
[
{
"id": 9,
"fecha_documento": "2019-02-01T09:30:57",
"tipo_documento": "01",
"clave_documento": "50601021900310174006200100001010000000947151840232",
"numero_documento": "00100001010000000947",
"emisor_nombre": "Empresa S.A.",
"emisor_nombre_comercial": null,
"emisor_identificacion": "3101740065",
"codigo_moneda": "CRC",
"total_comprobante": 50000,
"fecha_creacion": "2019-02-13T10:38:09"
}
]
Descripción
Permite obtener todos los datos de un borrador específico
HTTP METHOD: GET
URL de pruebas: https://dev.api.factun.com/api/V2/Recepcion/Borradores/{id}
URL de producción: https://api.factun.com/api/V2/Recepcion/Borradores/{id}
Parámetros
{id}: Identificador único de la recepción del buzón o borrador.
Respuestas
-
HTTP STATUS 404: Not Found: El id del borrador especificado no existe.
Deberá revisar que su id sea correcto.
-
HTTP STATUS 401: Unauthorized: Credenciales invalidas para la compania del documento.
Deberá revisar que el borrador solicitado este dentro del contexto correcto, o sea, que corresponda a la compañia a la cual el token representa.
Nadie debería intentar acceder a documentos que no le pertenecen.
-
HTTP STATUS 200: OK: La llamada ha sido completada.
La salida será un objeto JSON que representa una lista de borradores.
Puede revisar la documentación del objeto aqui (RecepcionBorrador JSON Salida)
A continuación se muestra un ejemplo de una respuesta exitosa:
{
"id": 9,
"fecha_documento": "2019-02-01T09:30:57",
"xml": "PD94bWwgdmVyc2...",
"tipo_documento": "01",
"clave_documento": "50601021900310174006200100001010000000947151840232",
"numero_documento": "00100001010000000947",
"emisor_nombre": "Empresa S.A.",
"emisor_nombre_comercial": null,
"emisor_identificacion": "3101740062",
"codigo_moneda": "CRC",
"total_comprobante": 50000,
"fecha_creacion": "2019-02-13T10:38:09",
"importado": false,
"descartado": false,
"accion_aplicada_por": null,
"fecha_accion": null
}
Descripción
Permite actualizar los datos de muchos borradores. Esto permite una secuencia en el flujo, ya que al obtener los borradores con el GET, el usuario podra marcarlos para importar o descartar, finalmente esas acciones podra enviarlas a Factun por medio de este método.
HTTP METHOD: PUT
URL de pruebas: https://dev.api.factun.com/api/V2/Recepcion/Borradores
URL de producción: https://api.factun.com/api/V2/Recepcion/Borradores
Parámetros
[ {RecepcionAccionBorrador}, {RecepcionAccionBorrador}, ... ]: Arreglo de elementos de la clase (RecepcionAccionBorradorJSON Entrada). Esto permite enviar una o muchas acciones.
A continuación se muestra un ejemplo del JSON de entrada:
[
{
"id": 8,
"accion": "IMPORTAR",
"resolucion": "ACEPTADO"
},
{
"id": 9,
"accion": "DESCARTAR",
"resolucion": ""
}
]
Respuestas
-
HTTP STATUS 200: OK: La llamada ha sido completada.
La salida será un objeto JSON que representa el estado de la transacción.
Para mas detalles de la clase Resultado: aqui
A continuación se muestra un ejemplo de una respuesta exitosa:
{
"exito": true,
"id": 0,
"data": {},
"mensajes": {}
}
A continuación se muestra un ejemplo de un error de validación:
{
"exito": false,
"id": 0,
"data": {},
"mensajes": {
"codigo_mensaje": "18-D",
"mensaje": "El siguiente borrador no pertenece a la compania de su cuenta: 7",
"detalle_mensaje": "Por favor validar el identificador unico del borrador."
}
}
Descripción
Permite la recepción de documentos por medio de API FACTUN. Este método permite subir el XML de un documento emitido hacia usted y enviar al ente gubernamental su resolución (Aceptado, Aceptado Parcialmente, Rechazado).
HTTP METHOD: POST
URL de pruebas: https://dev.api.factun.com/api/V2/Recepcion/Procesar
URL de producción: https://api.factun.com/api/V2/Recepcion/Procesar
Parámetros
RecepcionJSON: Objeto JSON con todos los metadatos necesarios para tramitar una recepción. Este JSON debe estar presente en el HTTP BODY.
Puede revisar la documentación del objeto aqui (Recepcion JSON Entrada)
A continuación se muestra un ejemplo del objeto JSON de entrada:
{
"resolucion" : 1,
"detalle" : "yo acepto este documento",
"clave_recepcion": "50620071800310137293500100001050000000006110694040",
"xml": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTg..."
}
Errores de validación
La clave del comprobante debe contener 50 caracteres. La clave no cumple con los requerimientos necesarios.
El XML a procesar es requerido. El objeto JSON no tiene presente la propiedad xml.
El largo del detalle no puede ser mas de 80 caracteres. El largo del detalle no cumple con las especificaciones.
La resolución debe ser 1:Aceptado, 2:Aceptado Parcialmente o 3:Rechazado. El número de resolucion no corresponde a los valores correctos.
Respuestas
-
HTTP STATUS 404: Not Found: La clave especificada no existe.
Deberá revisar que su clave está completa y es correcta.
-
HTTP STATUS 401: Unauthorized: Credenciales invalidas para la sucursal del documento.
Deberá revisar que la clave sea de un documento que esté dentro del contexto correcto, o sea, que corresponda a la sucursal y compañia a la cual el token representa.
Nadie debería intentar acceder a documentos que no le pertenecen.
-
HTTP STATUS 200: OK: La llamada ha sido completada.
La salida será un objeto JSON que representa el estado de la transacción y del documento.
Para mas detalles de la clase Resultado: aqui
A continuación se muestra un ejemplo de una respuesta exitosa:
{
"exito": true,
"id": 279,
"data": {
"clave_recepcion": "50620071800310137293500100001050000000006110694040",
"fecha_resolucion": "2019-01-10T15:02:04",
"estado_recepcion": "ENVIADO"
},
"mensajes": {}
}
Interpretacion del atributo data:
- clave_recepcion: Representa la clave electronica de la recepción. Tiene un tamaño de 50 caracteres.
- fecha_resolucion: Representa la fecha de emision de la recepción, automaticamente generada al momento de enviar el documento. Se despliega en el siguiente formato: yyyy-MM-ddTHH:mm:ss
- estado_recepcion: "ENVIADO" o "NO_ENVIADO" indica de manera sencilla si la recepción se envio sin errores al ente gubernamental o no. En caso de "NO_ENVIADO", debe utilizar el método Recepcion/Reenviar para intentar enviar el documento de nuevo. Si usted invoca el método procesar de nuevo con un mismo documento, se crearan dos recepciones separadas aunque sea el mismo documento.
A continuación se muestra un ejemplo de una respuesta NO exitosa:
{
"exito": false,
"id": 279,
"data": {
"clave_recepcion": "50620071800310137293500100001050000000006110694040",
"fecha_resolucion": "2019-01-10T15:02:04",
"estado_recepcion": "NO_ENVIADO"
},
"mensajes": {
"codigo_mensaje": "14"
"mensaje": "Error al enviar la recepcion al ente gubernamental",
"detalle": "{datos extra del error}"
}
}
Descripción
Permite reenviar una recepción existente que este NO ENVIADA al ente gubernamental debido usualmente a un error al enviar en el método procesar.
HTTP METHOD: POST
URL de pruebas: https://dev.api.factun.com/api/V2/Recepcion/Reenviar/{clave}
URL de producción: https://api.factun.com/api/V2/Recepcion/Reenviar/{clave}
Parámetros
{clave}: El único parámetro aceptado. Debe ser enviada en el URL. Representa la clave numérica de 50 caracteres asociada a la recepción.
Respuestas
-
HTTP STATUS 404: Not Found: La clave especificada no existe.
Deberá revisar que su clave está completa y es correcta.
-
HTTP STATUS 401: Unauthorized: Credenciales invalidas para la sucursal del documento.
Deberá revisar que la clave sea de un documento que esté dentro del contexto correcto, o sea, que corresponda a la sucursal y compania a la cual el token representa.
Nadie debería intentar acceder a documentos que no le pertenecen.
-
HTTP STATUS 200: OK: La llamada ha sido completada.
La salida será un objeto JSON que representa el estado de la transacción y del documento.
Para mas detalles de la clase Resultado: aqui
A continuación se muestra un ejemplo de una respuesta exitosa:
{
"exito": true,
"id": 277,
"data": {
"clave_recepcion": "50620071800310137293500100001050000000006110694040",
"fecha_resolucion": "2019-01-10T15:54:25",
"estado_recepcion": "ENVIADO"
},
"mensajes": {}
}
Interpretacion del atributo data:
- clave_recepcion: Representa la clave electronica de la recepción. Tiene un tamaño de 50 caracteres.
- fecha_resolucion: Representa la fecha de emision de la recepción, automaticamente generada al momento de enviar el documento. Se despliega en el siguiente formato: yyyy-MM-ddTHH:mm:ss
- estado_recepcion: "ENVIADO" o "NO_ENVIADO" indica de manera sencilla si el documento se envio sin errores al ente gubernamental o no. En caso de "NO_ENVIADO", debe utilizar el método Recepcion/Reenviar para intentar enviar el documento de nuevo. Si usted invoca el método procesar de nuevo con un mismo documento, se crearan dos recepciones separadas aunque sea el mismo documento.
A continuación se muestra un ejemplo de una respuesta NO exitosa:
{
"exito": false,
"id": 279,
"data": {
"clave_recepcion": "50620071800310137293500100001050000000006110694040",
"fecha_resolucion": "2019-01-10T15:02:04",
"estado_recepcion": "NO_ENVIADO"
},
"mensajes": {
"codigo_mensaje": "14"
"mensaje": "Error al enviar la recepcion al ente gubernamental",
"detalle": "{datos extra del error}"
}
}
Descripción
Permite consultar el estado (respuesta) del ente gubernamental para una recepción y guarda la respuesta para la recepción.
HTTP METHOD: PUT
URL de pruebas: https://dev.api.factun.com/api/V2/Recepcion/Consultar/{clave}
URL de producción: https://api.factun.com/api/V2/Recepcion/Consultar/{clave}
Parámetros
{clave}: El único parámetro aceptado. Debe ser enviada en el URL. Representa la clave numérica de 50 caracteres asociada al documento.
Respuestas
-
HTTP STATUS 404: Not Found: La clave especificada no existe.
Deberá revisar que su clave está completa y es correcta.
-
HTTP STATUS 401: Unauthorized: Credenciales invalidas para la sucursal del documento.
Deberá revisar que la clave sea de un documento que esté dentro del contexto correcto, o sea, que corresponda a la sucursal y compania a la cual el token representa.
Nadie debería intentar acceder a documentos que no le pertenecen.
-
HTTP STATUS 200: OK: La llamada ha sido completada.
La salida será un objeto JSON que representa el estado de la transacción y del documento.
A continuación se muestra un ejemplo de una respuesta exitosa:
{
"exito": true,
"id": 277,
"data": {
"clave": "50620071800310137293500100001050000000006110694040",
"estado_hacienda": "08",
"numero_documento": "00100001050000000006"
},
"mensajes": {
"detalle_mensaje": null,
"mensaje": "PROCESANDO",
"codigo_mensaje": "0"
}
}
Interpretacion del atributo data:
- clave: Representa la clave electronica de la recepción. Tiene un tamaño de 50 caracteres.
- estado_hacienda: Representa los diferentes estados de la recepción en la Factun. Estos estados reflejan su situación ante el ente gubernamental.
- numero_documento: Representa el número de documento que se encuentra en la clave del documento. Este número es de 20 caracteres.
Descripción
Permite obtener el XML creado en Factun utilizando clave de la recepción.
HTTP METHOD: GET
URL de pruebas: https://dev.api.factun.com/api/V2/Recepcion/XML/{clave}
URL de producción: https://api.factun.com/api/V2/Recepcion/XML/{clave}
Parámetros
{clave}: El único parámetro aceptado. Debe ser enviada en el URL. Representa la clave numérica de 50 caracteres asociada al documento.
Respuestas
-
HTTP STATUS 404: Not Found: La clave especificada no existe.
Deberá revisar que su clave está completa y es correcta.
-
HTTP STATUS 401: Unauthorized: Credenciales invalidas para la sucursal del documento.
Deberá revisar que la clave sea de un documento que esté dentro del contexto correcto, o sea, que corresponda a la sucursal y compania a la cual el token representa.
Nadie debería intentar acceder a documentos que no le pertenecen.
-
HTTP STATUS 200: OK: La llamada ha sido completada.
La salida será un XML plano.
Observe un ejemplo del contenido en RESPONSE BODY de la llamada:
Descripción
Permite obtener el XML de respuesta del ente gubernamental utilizando la clave de la recepción.
HTTP METHOD: GET
URL de pruebas: https://dev.api.factun.com/api/V2/Recepcion/RespuestaXML/{clave}
URL de producción: https://api.factun.com/api/V2/Recepcion/RespuestaXML/{clave}
Parámetros
{clave}: El único parámetro aceptado. Debe ser enviada en el URL. Representa la clave numérica de 50 caracteres asociada al documento.
Respuestas
-
HTTP STATUS 404: Not Found: La clave especificada no existe.
Deberá revisar que su clave está completa y es correcta.
-
HTTP STATUS 401: Unauthorized: Credenciales invalidas para la sucursal del documento.
Deberá revisar que la clave sea de un documento que esté dentro del contexto correcto, o sea, que corresponda a la sucursal y compania a la cual el token representa.
Nadie debería intentar acceder a documentos que no le pertenecen.
-
HTTP STATUS 200: OK: La llamada ha sido completada.
La salida será un XML plano.
Observe un ejemplo del contenido en RESPONSE BODY de la llamada:
