Métodos

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/Enviar44 (se crea el documento y se envía al ente gubernamental en un solo paso)
1. Si estado_hacienda es igual a ENVIADO (04)
  - El documento se encuentra bien, puede continuar con la llamada a consultar.
2. 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)
1. Si estado_hacienda es igual a ACEPTADO (01), ACEPTADO PARCIALMENTE (02) o RECHAZADO (03)
  - El documento tiene una resolución final, no hay más acciones de modificación al documento
2. 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).
1. Si estado_hacienda es igual a ENVIADO (04).
  - La recepción se encuentra bien, puede continuar con la llamada a consultar.
2. 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)
1. Si estado_hacienda es igual a ACEPTADO (01), ACEPTADO PARCIALMENTE (02) o RECHAZADO (03)
  - La recepción tiene una resolución final, no hay más acciones de modificación a la recepción.
2. 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 de 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 ayudará a interpretar los valores de "estado_hacienda":

00: Pendiente, el documento ha sido creado, pero no se ha 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 se ha 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 crear un documento en la nueva versión 4.4. 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.

🧪 Pruebas: https://dev.api.factun.com/api/V4/Documento/Enviar44

🚀 Producción: https://api.factun.com/api/V4/Documento/Enviar44

⚠️ Asegúrese de tener cuidado al enviar datos reales a este entorno.

Parámetros

DocumentoJSON: Objeto en formato JSON que encapsula los metadatos completos del documento. Este objeto debe incluirse en el HTTP BODY de la petición.

Puede revisar la documentación del objeto aquí (Documento JSON Entrada)

Ver ejemplo del objeto JSON de entrada

{
    "id_externo": "632541",
    "tipo_documento": "01",
    "codigo_actividad": "721001",
    "fecha_emision": "2025-07-20T11:30:00",
    "condicion_venta": "01",
    "plazo_credito": null,
    "medio_pago": [
        "01"
    ],    
    "receptor": {
        "razon_social": "Juan Federico Gonzalez",
        "identificacion": {
            "tipo": "01",
            "numero": "206380095"
        },
        "razon_comercial": "Juan",
        "codigo_actividad_receptor": "011901",
        "ubicacion": {
            "provincia": "2",
            "canton": "01",
            "distrito": "01",
            "barrio": "Barrio San Roque",
            "otras_senas": "50 metros norte de la Escuela Juan Bautista"
        },
        "telefono": {
            "codigo_pais": "506",
            "num_telefono": "85688785"
        },
        "correo_electronico": "federico@compañía.co.cr;amigos@compañía.co.cr"
    },
    "detalles": [
        {
            "numero_linea": 1,
            "codigo": "4526300000000",
            "cantidad": 2,
            "unidad_medida": "Unid",
            "unidad_medida_comercial": null,
            "tipo_codigo_comercial": "04",
            "codigo_comercial": "IMP-02",
            "tipo_transaccion" : "01"
            "detalle": "Impresora Epson",
            "precio_unitario": 47500,
            "porcentaje_descuento": 10,
            "naturaleza_descuento": "Promoción",
            "codigo_descuento" : "06"
            "impuesto": [
                {
                    "codigo": "01",
                    "tarifa": 13,
                    "codigo_tarifa": "08",
                    "exoneracion": {
                        "tipo_documento": "04",
                        "numero_documento": "AL-00022741-25",
                        "nombre_institucion": "01",
                        "fecha_emision": "2025-02-11T00:00:00",
                        "porcentaje_exoneracion": 13
                    }
                }
            ],
            
        }
    ],
    "otros_cargos":[
        {
            "tipo_documento": "04",
            "numero_identidad_tercero": "206530738",
            "tipo_identificacion_tercero"":"01",
            "nombre_tercero":"ANDREA ARIAS JARA",
            "detalle":"Cobro de un tercero",
            "monto_cargo" : 1500
        }
    ],    
    "resumen_documento": {
        "codigo_moneda": "CRC",
        "tipo_cambio": 1
    }
}

Respuestas

❌HTTP 404: Not Found La clave especificada no existe en el sistema.

Deberá revisar que su clave está completa y es correcta.
🔒HTTP 401: Unauthorized Credenciales inválidas para la sucursal del documento o token fuera de contexto.

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 200: OK La llamada ha sido completada exitosamente.

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": "692",
            "clave": "50624022500310137293500100001010000000692111651298",
            "numero_factura": "00100001010000000692",
            "estado_hacienda": "04",
            "moneda": "CRC",
            "total_comprobante": "97519"
        },
        "mensajes": {}
    }
               
```
Interpretación 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 del documento en Factun. Estos estados reflejan su situación 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."
        }
    }
                
```
GET api/v2/Documento/{clave}

Descripción

Permite obtener la información completa de un documento a partir de la clave del mismo.

🧪 Pruebas: https://dev.api.factun.com/api/V2/Documento/{clave}

🚀 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 404: Not Found La clave especificada no existe.
  Deberá revisar que su clave esté completa y es correcta.
- 🔒HTTP 401: Unauthorized Credenciales inválidas 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 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."
    }
```
PUT api/v2/Documento/Consultar/{clave}

Descripción

Permite consultar el estado (respuesta) del ente gubernamental al documento y guardar la respuesta para el documento.

🧪 Pruebas: https://dev.api.factun.com/api/V2/Documento/Consultar/{clave}

🚀 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 404: Not Found La clave especificada no existe.
  Deberá revisar que su clave está completa y es correcta.
- 🔒HTTP 401: Unauthorized Credenciales inválidas 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 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 un 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 un 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 debido 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"
        }
    }
```
PUT api/v2/Documento/Reenviar/{clave}

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).

🧪 Pruebas: https://dev.api.factun.com/api/V2/Documento/Reenviar/{clave}

🚀 Producción: https://api.factun.com/api/V2/Documento/Reenviar/{clave}
⚠️ Asegúrese de tener cuidado al enviar datos reales a este entorno.
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 404: Not Found La clave especificada no existe.
  Deberá revisar que su clave está completa y es correcta.
- 🔒HTTP 401: Unauthorized Credenciales inválidas 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 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 trató 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"
        }
    }
```
POST api/v2/Documento/Notificar

Descripción

Permite reenviar una notificación de correo para un documento, ya sea a toda la lista original mas otros destinatarios o solamente a unos nuevos destinatarios.

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.

🧪 Pruebas: https://dev.api.factun.com/api/V2/Documento/Notificar

🚀 Producción: https://api.factun.com/api/V2/Documento/Notificar
⚠️ Asegúrese de tener cuidado al enviar datos reales a este entorno.
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 aquí (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
- Destinatario es requerido. Debe indicar los correos separados por punto y coma(;). Esto aplica cuando "nuevo_envio" es TRUE.
- Destinatarios incorrectos o inválidos. Solamente se aceptan correos electrónicos válidos separados por punto y coma (;). Evite espacios en la cadena.
Respuestas
- ❌HTTP 404: Not Found La clave especificada no existe.
  Deberá revisar que su clave está completa y es correcta.
- 🔒HTTP 401: Unauthorized Credenciales inválidas 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 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": "Destinatario es requerido",
            "codigo_mensaje": "15"
        }
    }    
```
GET api/v2/Documento/XML/{clave}

Descripción

Permite obtener el XML creado por Factun utilizando la clave del documento.

🧪 Pruebas: https://dev.api.factun.com/api/V2/Documento/XML/{clave}

🚀 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 404: Not Found La clave especificada no existe.
  Deberá revisar que su clave está completa y es correcta.
- 🔒HTTP 401: Unauthorized Credenciales inválidas 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 200: OK La llamada ha sido completada.
  La salida será un xml plano.
  
  Observe un ejemplo del contenido en RESPONSE BODY de la llamada:
GET api/v2/Documento/RespuestaXML/{clave}

Descripción

Permite obtener el XML de respuesta del ente gubernamental utilizando la clave del documento.

🧪 Pruebas: https://dev.api.factun.com/api/V2/Documento/RespuestaXML/{clave}

🚀 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 404: Not Found La clave especificada no existe.
  Deberá revisar que su clave está completa y es correcta.
- 🔒HTTP 401: Unauthorized Credenciales inválidas 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 200: OK La llamada ha sido completada.
  La salida será un xml plano.
  
  Observe un ejemplo del contenido en RESPONSE BODY de la llamada:
GET api/v2/Recepcion/Borradores

Descripción

Los 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 compañía a la cual el token representa.

🧪 Pruebas: https://dev.api.factun.com/api/V2/Recepcion/Borradores

🚀 Producción: https://api.factun.com/api/V2/Recepcion/Borradores

Parámetros

Sin parámetros

Respuestas
- ✅HTTP 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"
        }
    ]
```
GET api/v2/Recepcion/Borradores/{id}

Descripción

Permite obtener todos los datos de un borrador específico

🧪 Pruebas: https://dev.api.factun.com/api/V2/Recepcion/Borradores/{id}

🚀 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 404: Not Found El id del borrador especificado no existe.
  Deberá revisar que su id sea correcto.
- 🔒HTTP 401: Unauthorized Credenciales inválidas para la compañía del documento.
  Deberá revisar que el borrador solicitado esté 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 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í (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
    }
```
PUT api/v2/Recepcion/Borradores

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 podrá marcarlos para importar o descartar, finalmente esas acciones podrá enviarlas a Factun por medio de este método.

🧪 Pruebas: https://dev.api.factun.com/api/V2/Recepcion/Borradores

🚀 Producción: https://api.factun.com/api/V2/Recepcion/Borradores
⚠️ Asegúrese de tener cuidado al enviar datos reales a este entorno.
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",
            "condicion_impuesto": "01"
        },    
        {
            "id": 9,
            "accion": "DESCARTAR",
            "resolucion": ""
        }
    ]
```
Respuestas
- ✅HTTP 200: OK La llamada ha sido completada.
  La salida será un objeto JSON que representa el estado de la transacción.
  
  Para más detalles de la clase Resultado: aquí
  
  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 compañía de su cuenta: 7",
            "detalle_mensaje": "Por favor validar el identificador único del borrador."
        }
    }
```
POST api/v2/Recepcion/Procesar

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).

🧪 Pruebas: https://dev.api.factun.com/api/V2/Recepcion/Procesar

🚀 Producción: https://api.factun.com/api/V2/Recepcion/Procesar
⚠️ Asegúrese de tener cuidado al enviar datos reales a este entorno.
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 aquí (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 404: Not Found La clave especificada no existe.
  Deberá revisar que su clave está completa y es correcta.
- 🔒HTTP 401: Unauthorized Credenciales inválidas 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 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 más detalles de la clase Resultado: aquí
  
  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": {}
    }
```
  Interpretación del atributo data:
  - clave_recepcion: Representa la clave electrónica de la recepción. Tiene un tamaño de 50 caracteres.
  - fecha_resolucion: Representa la fecha de emisión de la recepción, automáticamente 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 envió 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 crearán 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}"
        }
    }	            
```
POST api/v2/Recepcion/Reenviar/{clave}

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.

🧪 Pruebas: https://dev.api.factun.com/api/V2/Recepcion/Reenviar/{clave}

🚀 Producción: https://api.factun.com/api/V2/Recepcion/Reenviar/{clave}
⚠️ Asegúrese de tener cuidado al enviar datos reales a este entorno.
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 404: Not Found La clave especificada no existe.
  Deberá revisar que su clave está completa y es correcta.
- 🔒HTTP 401: Unauthorized Credenciales inválidas 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 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 más detalles de la clase Resultado: aquí
  
  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": {}
    }        
```
  Interpretación del atributo data:
  - clave_recepcion: Representa la clave electrónica de la recepción. Tiene un tamaño de 50 caracteres.
  - fecha_resolucion: Representa la fecha de emisión de la recepción, automáticamente 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 envió 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 crearán 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}"
        }
    }	            
```
PUT api/v2/Recepcion/Consultar/{clave}

Descripción

Permite consultar el estado (respuesta) del ente gubernamental para una recepción y guarda la respuesta para la recepción.

🧪 Pruebas: https://dev.api.factun.com/api/V2/Recepcion/Consultar/{clave}

🚀 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 404: Not Found La clave especificada no existe.
  Deberá revisar que su clave está completa y es correcta.
- 🔒HTTP 401: Unauthorized Credenciales inválidas 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 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"
    }
}
```
  Interpretación del atributo data:
  - clave: Representa la clave electrónica de la recepción. Tiene un tamaño de 50 caracteres.
  - estado_hacienda: Representa los diferentes estados de la recepción en 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.
GET api/v2/Recepcion/XML/{clave}

Descripción

Permite obtener el XML creado en Factun utilizando clave de la recepción.

🧪 Pruebas: https://dev.api.factun.com/api/V2/Recepcion/XML/{clave}

🚀 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 404: Not Found La clave especificada no existe.
  Deberá revisar que su clave está completa y es correcta.
- 🔒HTTP 401: Unauthorized Credenciales inválidas 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 200: OK La llamada ha sido completada.
  La salida será un XML plano.
  
  Observe un ejemplo del contenido en RESPONSE BODY de la llamada:
GET api/v2/Recepcion/RespuestaXML/{clave}

Descripción

Permite obtener el XML de respuesta del ente gubernamental utilizando la clave de la recepción.

🧪 Pruebas: https://dev.api.factun.com/api/V2/Recepcion/RespuestaXML/{clave}

🚀 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 404: Not Found La clave especificada no existe.
  Deberá revisar que su clave está completa y es correcta.
- 🔒HTTP 401: Unauthorized Credenciales inválidas 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 200: OK La llamada ha sido completada.
  La salida será un XML plano.
  
  Observe un ejemplo del contenido en RESPONSE BODY de la llamada:

Lista de métodos (API FACTUN V2)

Flujo API FACTUN

Estándar de respuesta API FACTUN

Estado Hacienda

POST api/v4/Documento/Enviar44

Descripción

Parámetros

Respuestas

Errores de Validación

GET api/v2/Documento/{clave}

Descripción

Parámetros

Respuestas

PUT api/v2/Documento/Consultar/{clave}

Descripción

Parámetros

Respuestas

PUT api/v2/Documento/Reenviar/{clave}

Descripción

Parámetros

Respuestas

POST api/v2/Documento/Notificar

Descripción

Parámetros

Errores de validación

Respuestas

GET api/v2/Documento/XML/{clave}

Descripción

Parámetros

Respuestas

GET api/v2/Documento/RespuestaXML/{clave}

Descripción

Parámetros

Respuestas

GET api/v2/Recepcion/Borradores

Descripción

Parámetros

Respuestas

GET api/v2/Recepcion/Borradores/{id}

Descripción

Parámetros

Respuestas

PUT api/v2/Recepcion/Borradores

Descripción

Parámetros

Respuestas

POST api/v2/Recepcion/Procesar

Descripción

Parámetros

Errores de validación

Respuestas

POST api/v2/Recepcion/Reenviar/{clave}

Descripción

Parámetros

Respuestas

PUT api/v2/Recepcion/Consultar/{clave}

Descripción

Parámetros

Respuestas

GET api/v2/Recepcion/XML/{clave}

Descripción

Parámetros

Respuestas

GET api/v2/Recepcion/RespuestaXML/{clave}

Descripción

Parámetros

Respuestas