Esta guía te ayuda a hacer tu primera llamada a la API de FacturaDirecta. En pocos pasos tendrás una conexión funcional.

💡 Recomendación: Haz tus primeras pruebas en un entorno de pruebas (sandbox) antes de usar la API en producción. Los sandboxes tienen datos aislados y puedes experimentar sin afectar tu empresa real.

Requisitos previos

Antes de empezar, necesitas:

Una cuenta en FacturaDirecta (el plan gratuito es suficiente)
Tu companyId (identificador de empresa)
Una clave de API con los permisos necesarios

👉 Si aún no tienes una clave de API, consulta Cómo crear claves de API.

Tu primera llamada

Vamos a listar tus facturas. Abre una terminal y ejecuta:

curl -H "facturadirecta-api-key: TU_CLAVE_API" \
     https://app.facturadirecta.com/api/TU_COMPANY_ID/invoices

Sustituye:

TU_CLAVE_API por tu clave de API
TU_COMPANY_ID por tu identificador de empresa

Entender la respuesta

Si todo va bien, recibirás una respuesta JSON con tus facturas:

{
  "data": [
    {
      "id": "inv_abc123",
      "number": "2026-001",
      "date": "2026-01-15",
      "contact": {
        "id": "con_xyz789",
        "name": "Cliente Ejemplo S.L."
      },
      "total": 121.00,
      "currency": "EUR",
      "state": "sent"
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 25,
    "total": 150
  }
}

La respuesta incluye:

data: Array con los registros
pagination: Información para paginar resultados

Siguiente paso: crear una factura

Una vez que puedas leer datos, el siguiente paso es crear registros. Este ejemplo crea una factura básica:

curl -X POST \
     -H "facturadirecta-api-key: TU_CLAVE_API" \
     -H "Content-Type: application/json" \
     -d '{
       "contactId": "con_xyz789",
       "date": "2026-01-27",
       "lines": [
         {
           "description": "Servicio de consultoría",
           "quantity": 1,
           "unitPrice": 100.00
         }
       ]
     }' \
     https://app.facturadirecta.com/api/TU_COMPANY_ID/invoices

Errores comunes

Error 401: Unauthorized

La clave de API no es válida o no está presente. Verifica:

Que la cabecera se llama facturadirecta-api-key (no Authorization)
Que la clave está copiada correctamente
Que la clave no ha sido eliminada

Error 403: Forbidden

La clave no tiene permisos para esta operación. Verifica:

Que la clave tiene el permiso correspondiente (ej: invoices:read para leer facturas)
Que el companyId es de la empresa donde se creó la clave

Error 404: Not Found

El recurso no existe. Verifica:

Que el companyId es correcto
Que la ruta del endpoint es correcta
Que el ID del recurso existe

Siguientes pasos

Ahora que tienes una conexión funcionando:

Explora la especificación OpenAPI para ver todos los endpoints disponibles
Importa la especificación en Postman o Insomnia para probar los endpoints de forma visual
Genera un cliente para tu lenguaje de programación con herramientas como OpenAPI Generator

Inicio rápido con la API