Introducción

¿Qué es el API FACTUN?

El API FACTUN es una interfaz que permite la creación de documentos electrónicos (facturas, tiquetes, notas de crédito y débito) en su cuenta de servicios de la plataforma FACTUN a través de un REST API. Esto es muy útil cuando usted ya cuenta con sistemas propios en su negocio y desea que FACTUN se encargue de la facturación electrónica mientras usted conserva sus sistemas informáticos.

Usted puede realizar las siguientes acciones a través del API FACTUN:

• Crear un documento y enviarlo al ente gubernamental.
• Reenviar el documento en caso de error.
• Consultar los datos de un documento especifico.
• Descargar el XML generado para un documento especifico.
• Consultar la respuesta del ente gubernamental a un documento especifico.
• Descargar el XML de respuesta del ente gubernamental al documento.

También el API FACTUN puede ayudarle en la recepción de documentos electrónicos:

• Crear una recepción y enviarla al ente gubernamental.
• Reenviar una recepción en caso de error.
• Descargar el XML generado para una recepción especifica.
• Consultar la respuesta del ente gubernamental a una recepción especifica.
• Descargar el XML de respuesta del ente gubernamental a una recepción.

API FACTUN también puede encargarse de tareas como la notificación automática a sus clientes por correo electrónico de los documentos electrónicos generados.

¿Cómo empezar a utilizar el API?

Si usted ya posee una cuenta en la plataforma de FACTUN, solamente debe solicitar a nuestro soporte una activación API, nuestro soporte le proveerá las credenciales necesarias para usar nuestro API FACTUN.

Si usted no posee una cuenta en la plataforma de FACTUN, deberá registrarse en la plataforma primeramente para luego solicitar activación API a su cuenta.

La plataforma de Factun, cuenta con dos instancias o ambientes, cada una de estas plataformas es totalmente independiente, lo cual significa que usted se registra por aparte en cada ambiente y sus acciones son totalmente específicas para el ambiente en que este trabajando.

Instancia de Pruebas (Desarrollo)

Este ambiente está destinado a pruebas de integración y demostraciones de la plataforma FACTUN. Es muy útil cuando usted de sus primeros pasos con el API FACTUN y quiera familiarizarse con la plataforma sin ningún formalismo.

Usted debe registrarse en este ambiente de la misma manera que lo haría en producción, la diferencia es que las credenciales que usted especifica deben ser las credenciales de prueba que el ente gubernamental le ha provisto.

Instancia de Producción

Ambiente real para los servicios de Factun. Debe siempre especificar las credenciales de producción provistas por el ente gubernamental.

¿Cómo acceso API FACTUN?

Una vez que usted ya se encuentra en la plataforma de FACTUN, nuestro soporte podrá proveerle los siguientes datos:

• Usuario: nombre de usuario api utilizado para la autenticación.
• Contraseña: contraseña del usuario api a autenticar
• Token: identificador único que permite agregar una dato extra de seguridad y permite identificar sobre cual combinación de Compañía-Sucursal desea trabajar.

Autenticación

El API FACTUN utiliza Basic Authentication sobre HTTPS como método de autenticación. A parte de Basic Authencation, usted debe agregar un header llamado "FactunToken" que contenga el token que se le ha provisto.

A continuación se ilustra como se observa una autenticación de ejemplo mediante la aplicación POSTMAN:

Errores

Usted puede recibir las siguientes respuestas de error al intentar una autenticación incorrecta:

• HTTP STATUS 401: Unauthorized: No se encontraron credenciales.

  Deberá revisar que el header para basic authenticacion está correctamente presente en la llamada HTTP.

• HTTP STATUS 401: Unauthorized: No se encontró el FactunToken.

  Deberá revisar que el header para el token esta correctamente presente en la llamada HTTP.

• HTTP STATUS 401: Unauthorized: Credenciales inválidas.

  Su combinación de usuario y contraseña no es válida.

Consecutivos

API FACTUN puede utilizar claves y consecutivos generados por un sistema externo o puede usar directamente los consecutivos establecidos para la sucursal en la configuración de Factun (recuerde que el token permite determinar cuál sucursal se usa).

Versionamiento

Como cualquier otro API, se utiliza versionamiento. Siempre debe incluir la version en el URL despues del prefijo /api/, por ejemplo: https://dev.api.factun.com/api/V2/Documento/{clave}

Si existe algún error con el versionamiento, se informará con el HTTP CODE 400 (Bad Request) y con un objeto JSON para informar el error, por ejemplo:

        {
            "Error": {
                "Code": "ApiVersionUnspecified",
                "Message": "An API version is required, but was not specified."
            }
        }      

Si se invoca un método que no existe, o se utiliza un HTTP METHOD incorrecto o algún error similar, usualmente se informara con un 405 (Method Nor Allowed), por ejemplo:

    {
    "Error": {
        "Code": "UnsupportedApiVersion",
        "Message": "The requested resource with API version '2' does not support HTTP method 'PUT'.",
        "InnerError": {
            "Message": "No route providing a controller name with API version '2' was found to match HTTP method 'PUT' and request URI 'http://localhost:58354/api/V2/Documento/Notificar'."
        }
    }
}