1. Introducción
2. Cómo probar la API de forma gratuita
3. Envío de las facturas proforma
4. Respuesta JSON
5. Enlace predictivo
6. Consideraciones importantes

1. Introducción

La API de Facturantia permite a aplicaciones externas (como e-commerce, ERP u otros programas de gestión) importar proformas en formato XML, emitirlas conforme a la Ley Antifraude (SIF Verifactu y No Verifactu) y generar un enlace predictivo para que el cliente final descargue el PDF de la factura con el código QR tributario. Todo ello de forma automática y al instante para pequeños volúmenes y en apenas unos segundos para hasta 1.000 facturas por envío.

2. Cómo probar la API de forma gratuita

1. Crea una cuenta de prueba gratuita en Facturantia.com. (No probar con una cuenta con emisión de facturas en real hasta estar seguro).

2. Crea una empresa y rellena sus datos identificativos sin olvidarte de introducir un Certificado Digital válido.

3. Permite la conexión vía API en Facturantia > menú lateral izquierdo > Cuenta > Permitir conexión vía API > Introduce un Token personalizado y marca la casilla 'permitir'.

4. Descarga el fichero XML de ejemplo: proforma_ejemplo_api.xml.

5. Genera un comando curl de emisión como el que se muestra a continuación, pero adaptándolo a los datos de tu caso concreto, y ejecútalo en la consola de comandos.

   curl -X POST https://www.facturantia.com/API/proformas_receptor.php ^
   -H "X-Usuario-Email:usuario@email.com" ^
   -H "X-Token:token_personalizado" ^
   -H "X-Empresa-Nombre:DEMO API, S.A." ^
   -H "X-Empresa-Ejercicio:2025" ^
   -H "X-Accion:emitir" ^
   -H "Content-Type: application/xml" ^
   --data-binary "@C:\proforma_ejemplo_api.xml"

6. Si la respuesta de envío es correcta, crea un enlace como el que se muestra a continuación, pero adaptándolo a tu caso concreto. Recuerda que el enlace no se devuelve con la respuesta, puedes crearlo por anticipado de forma totalmente predictiva. Éste redirigirá al Área de Facturación para Clientes donde se podrá consultar la factura y descargar su PDF.

   https://www.facturantia.com/ver_afc_api.php?auid=111&aen=DEMO API&aej=2025&aeid=11&acn=A78106705

7. Importante: Para volver a repetir la prueba será necesario asignar un nuevo 'external_id' único a cada proforma que se desee emitir vía API.

3. Envío de las facturas proforma

• Formato XML: El cuerpo de la solicitud debe ser un archivo XML con una o varias proformas que cumplan el esquema XSD oficial de Facturantia: EsquemaProformas.xsd.

• Endpoint: POST https://www.facturantia.com/API/proformas_receptor.php.

• Content-Type: application/xml.

Además, todo acceso a la API requiere de los siguientes encabezados HTTP obligatorios:

• 'X-Usuario-Email':Email del usuario en Facturantia.com.

• 'X-Token': Crea tu Token personalizado. Puedes hacerlo desde Facturantia > Cuenta > Permitir conexión vía API > Crear Token.

• 'X-Empresa-Nombre': Nombre asignado a la empresa en el momento de su creación (no en los datos identificativos).

• 'X-Empresa-Ejercicio': Ejercicio contable de la empresa.

• 'X-Accion': 'emitir' o 'importar' (para emitirlas las facturas directamente o guardarlas como proformas).

Ejemplo con curl:

4. Respuesta JSON

La respuesta será un objeto JSON con los siguientes posibles campos:

• 'estado_envio_facturantia': 'CORRECTO' o 'INCORRECTO'.
• 'mensaje_error', 'mensaje_atencion' o 'mensaje_exito'.
• 'tipo_sif': 'VERIFACTU' o 'NO VERIFACTU'.
• 'verifactu_total_facturas_enviadas'.
• 'verifactu_total_facturas_correctas'.
• 'verifactu_total_facturas_aceptadas_con_errores'.
• 'verifactu_total_facturas_rechazadas'.
• 'numeros_facturas': Objeto JSON que relaciona 'external_id' con él 'numero_factura' asignado por la aplicación.
• 'enlaces_qr': Objeto JSON que relaciona 'external_id' con el 'enlace_qr' para generar el Código QR tributario.

Ejemplo de respuesta JSON cuando se emiten facturas con Verifactu:

Ejemplo de respuesta JSON cuando solo se importan proformas:

Ejemplo de respuesta JSON de error:

5. Enlace predictivo al PDF

El Cliente API puede construir el enlace al PDF sin necesidad de esperar una respuesta directa con el enlace. Solo necesita:

• 'auid': Usuario ID (Facturantia > menú lateral izquierdo > Cuenta > ID).

• 'aen': Nombre de la empresa emisora creada en Facturantia.

• 'aej': Ejercicio contable de la empresa emisora creada en Facturantia.

• 'aeid': 'external_id' asignado a la proforma por parte del Cliente API para identificarla de forma única por empresa-ejercicio (campo obligatorio que debe contener el XML de cada proforma).

• 'acn': NIF o Número de Documento del cliente destinatario de la factura.

Ejemplo de enlace predictivo:

6. Consideraciones importantes

• El XML debe cumplir el esquema oficial (EsquemaProformas.xsd). El sistema validará antes de importar.
• El campo 'external_id' asignado a cada proforma es obligatorio y debe ser único por empresa-ejercicio.
• Para poder consultar la factura mediante el enlace predictivo, el campo 'permitir_email_y_afc' debe ser igual a '1'.
• Si en la emisión Verifactu, la respuesta de la AEAT incluye errores, éstos no se devuelven de forma detallada. El usuario debe acceder a Facturantia para consultar las facturas incorrectas y corregirlas como considere oportuno: rectificando, abonando, anulando, etc.