Integración por API: entornos, campos obligatorios y asignación de campos

Este artículo responde a las preguntas más frecuentes sobre la conexión de sus propios sistemas a la API de faktoora. Los mensajes de error y los códigos de estado HTTP se describen por separado en el artículo Gestión de errores de la API, la lista completa de campos BT en el artículo ¿Qué campos BT admite la API de faktoora? y los campos obligatorios para XRechnung en el artículo ¿Qué datos mínimos necesita una XRechnung?.

Entorno de pruebas y entorno de producción

La API de faktoora está disponible en dos URL base independientes:

• Entorno de producción: https://api.faktoora.com/api/v1
• Entorno de demostración/pruebas: https://api.demo.faktoora.com/api/v1

Ambos entornos son instancias independientes con cuentas y datos propios. La clave de API se genera en los ajustes de la cuenta del entorno correspondiente y se transmite en la cabecera X-API-KEY (consulte ¿Por qué mis llamadas a la API se rechazan con un error 401?). Para pasar de las pruebas al uso en producción, cambie la URL base a https://api.faktoora.com/api/v1 y utilice la clave generada en la cuenta de producción.

Crear una factura: POST /invoices

En el propio objeto Invoice, según el esquema, solo los siguientes campos son obligatorios en principio:

• format: formato de salida, p. ej., simple, zf:1, zf:2, xrechnung, peppol
• issueDate: fecha de factura (BT-2)
• invoiceNumber: número de factura (BT-1)
• invoiceTypeCode: tipo de factura, p. ej., 380 para una factura comercial (BT-3)
• invoiceItems: al menos una línea de factura
• buyer: el comprador

Dentro de buyer y seller, el nombre y la dirección completa (street, postcode, city, country) son obligatorios en cuanto se envía el bloque correspondiente. Cada línea de invoiceItems necesita un id y un objeto product con name, quantity, unitCode, price y taxes. La lista completa de campos obligatorios, que depende del formato, para format: xrechnung se encuentra en el artículo ¿Qué datos mínimos necesita una XRechnung?.

Obtener una factura: proceso

La creación de facturas mediante POST /invoices es asíncrona: la respuesta es 202 Accepted con un faktooraId y la factura en sí se genera en segundo plano. Un GET /invoices/{faktooraId} inmediatamente después puede fallar con 404 porque el procesamiento todavía está en curso.

El proceso correcto:

1. Enviar POST /invoices y guardar el faktooraId de la respuesta 202.
2. Comprobar el estado de procesamiento mediante GET /invoices/{faktooraId}/status o esperar al webhook registrado (consulte Webhook).
3. Solo después, llamar a GET /invoices/{faktooraId}. El endpoint devuelve directamente el archivo terminado como application/pdf o application/xml (no un objeto JSON de metadatos).

Los detalles sobre los posibles códigos de estado se encuentran en el artículo Gestión de errores de la API.

Asignación de campos

Referencia del pedido (Order Reference)

A nivel de factura existen dos campos de referencia diferentes:

• orderNumber en el objeto Invoice: referencia al pedido correspondiente (BT-14).
• invoiceItems[].product.orderNumber: referencia del pedido a nivel de cada línea; según la descripción de la API, no está permitida para format: xrechnung.

Además existe buyerReference.IssuerAssignedID como referencia del pedido del comprador (BT-13), que debe distinguirse de buyerReference.buyerReferenceId: esta es la referencia del comprador o, en el caso de la administración pública, la Leitweg-ID (BT-10).

Al obtener datos de facturas a través de los endpoints de importación (véase más abajo), el campo correspondiente se denomina references.orderReferenceId (BT-13) o references.orderNumber para el número de pedido del comprador. Por tanto, los nombres de los campos difieren entre la creación (POST /invoices) y la consulta de facturas importadas.

Número de pedido: ¿a nivel de cabecera o de línea?

Ambas opciones son posibles e independientes entre sí: orderNumber en el objeto Invoice hace referencia al pedido a nivel de cabecera (BT-14) y invoiceItems[].product.orderNumber hace referencia a un pedido a nivel de cada línea. Para xrechnung solo se permite el nivel de cabecera.

Persona de contacto del comprador

La persona de contacto del comprador se gestiona mediante buyer.definedTradeContact:

• firstName / lastName: nombre de la persona de contacto (BT-56)
• departmentName: departamento (BT-56-0)
• phone: número de teléfono (BT-57-00)
• email: dirección de correo electrónico (BT-58-00)

Esto es independiente de buyer.phone/buyer.email (BT-57/BT-58), que reflejan el contacto general de la empresa compradora.

DirectDebitMandateID

directDebitMandateID (mandato de adeudo directo SEPA, BG-19/BT-89) pertenece al objeto specifiedTradePaymentTerms, no a specifiedTradeSettlementPaymentMeans. Si el campo se transmite por error en el bloque de medios de pago (Payment Means) en lugar de en el bloque de condiciones de pago (Payment Terms), no se incorpora al XML, porque allí no es un campo definido del esquema. Si falta DirectDebitMandateID en el XML generado, compruebe primero si el campo está en el array specifiedTradePaymentTerms.

Códigos de forma de pago para PayPal y tarjeta de crédito

El campo specifiedTradeSettlementPaymentMeans[].typeCode (BT-81) utiliza la lista de códigos UNTDID 4461. Están disponibles, entre otros, 10 (efectivo), 20 (cheque), 30 (transferencia), 42 (pago en cuenta bancaria), 48 (pago con tarjeta), 49 (adeudo directo), 57 (orden permanente), 58 (transferencia SEPA), 59 (adeudo directo SEPA), 97 (Report) y el código de texto ZZZ (definido libremente). No existe un código propio para PayPal.

• Tarjeta de crédito: typeCode: 48. Para este código se admiten además cardNumber (obligatorio) y, opcionalmente, holderName; ambos campos solo están permitidos con typeCode: 48.
• PayPal: como UNTDID 4461 no contiene ningún código específico para PayPal, utilice typeCode: "ZZZ" (definido libremente) y describa la forma de pago en el campo de texto libre information, p. ej., "Pago mediante PayPal".

Estructura de datos de la interfaz para facturas recibidas y emitidas

Para las facturas importadas, tanto recibidas (/import/incoming) como emitidas (/import/outgoing), la API devuelve la misma estructura básica, dividida en subrecursos que se pueden consultar por separado:

• content/summary: resumen (estado, importes, formato)
• content/seller / content/buyer: datos del vendedor o del comprador
• content/lineitems: líneas de factura
• content/taxes: datos fiscales por categoría fiscal (taxable, rate, amount, category)
• content/paymentterms: condiciones de pago, incluidos directDebitMandateID y dueDateTime
• content/paymentmeans: medios de pago (typeCode, information, paymentReference)
• content/delivery: datos de entrega
• content: todos los subrecursos anteriores reunidos en una sola respuesta
• attachments / attachment/{attachmentId}/file: archivos adjuntos de la importación
• status: estado de procesamiento de la importación
• validation / validation/pdf: resultado de la validación

La importación en sí es asíncrona: un POST /import/incoming devuelve 202 Accepted con un importId antes de que finalicen el análisis y la validación. Consulte GET /import/incoming/{importId}/status hasta que overallStatus deje de ser pending antes de evaluar los endpoints de contenido.

En las facturas emitidas importadas (/import/outgoing), content contiene además un bloque references con los números de referencia de todo el documento: orderNumber (número de pedido del comprador), orderReferenceId (BT-13), buyerReferenceId (BT-10), shippingOrderNumber, supplierNumber, contractNumber, assignmentNumber y mandateReference (referencia del mandato SEPA).

Facturas recurrentes

Las facturas recurrentes ("Facturas periódicas") se configuran en la interfaz de faktoora; las instrucciones paso a paso se encuentran en el artículo Facturas periódicas. En la API está disponible para ello el endpoint de lectura GET /recurring-invoices: devuelve las programaciones creadas (nombre, frecuencia, fecha de inicio/fin, estado, nextExecutionDate, plantilla de factura vinculada). En la referencia de la API no se documenta ningún endpoint para crear o modificar una programación a través de la API.

Intercambio de archivos: SFTP, FTP y WebDAV

Para intercambiar archivos de factura a través de un directorio, se puede configurar una conexión de archivos en los flujos de trabajo. Como protocolo se puede elegir entre FTP, SFTP y WebDAV. La configuración se realiza en la interfaz, no a través de la API: la referencia de la API no contiene endpoints para ello.

Además, hay otras dos formas de conectar un sistema previo:

• Mediante programación a través de la API: generar datos de factura estructurados con POST /invoices, o subir archivos de factura electrónica ya generados con POST /import/incoming o el equivalente para facturas emitidas.
• Por correo electrónico: consulte Recepción de facturas a través de un servidor de correo propio.

Integración con DATEV: tratamiento de las diferencias de importe

En la exportación a DATEV, faktoora compensa automáticamente las diferencias de redondeo entre la suma de las líneas de factura y el importe consolidado de la factura: si la suma de los importes de las líneas difiere del importe consolidado, la diferencia se imputa al importe de la primera línea en la exportación al libro mayor de DATEV, de modo que la suma de las líneas exportadas coincida exactamente con el importe total de la factura.

Sistemas ya integrados

En el código y en los artículos existentes de la base de conocimientos están documentadas las conexiones con: DATEV, Xero, weclapp, HubSpot, Monday, PipeDrive y Bexio. Además existe una conexión con Stripe que sincroniza las facturas y los clientes de Stripe como facturas en faktoora; la generación automática en formato XRechnung mediante esta conexión no está documentada. El formato de salida de una factura lo sigue determinando usted mismo mediante el campo format o los ajustes de la cuenta.