Inicio rápido con la API

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

Recomendación: haz tus primeras pruebas en un entorno de pruebas (sandbox) antes de usar la API en producción.

Requisitos previos#

Necesitas:

• Una cuenta en FacturaDirecta.
• Una empresa real o sandbox.
• El companyId de esa empresa.
• Una API key con los permisos necesarios.

Si todavía no tienes la clave o el companyId, consulta API keys en Ajustes.

Variables para los ejemplos#

Guarda estos valores en variables de entorno para copiar los ejemplos con menos riesgo de error:

export fd_company_id="com_tu_empresa"
export fd_api_key="tu_api_key"

La URL base de producción es:

export fd_api_base="https://app.facturadirecta.com/api"

Primera llamada: listar facturas#

Vamos a listar facturas de venta:

curl -s \
  -H "facturadirecta-api-key: $fd_api_key" \
  "$fd_api_base/$fd_company_id/invoices?limit=5"

Si todo va bien, recibirás una respuesta JSON. Las listas paginadas devuelven normalmente pagination e items:

{
  "pagination": {
    "offset": 0,
    "limit": 5,
    "total": 42
  },
  "items": [
    {
      "uuid": "inv_...",
      "main": {
        "date": "2026-01-15",
        "docNumber": { "series": "F-##-", "number": 1 },
        "currency": "EUR"
      }
    }
  ]
}

El contenido exacto de cada factura depende del schema público Invoice. Consulta Facturas de venta para el detalle del recurso.

Probar un recurso más simple: contactos#

Si tu empresa todavía no tiene facturas, puedes probar con contactos:

curl -s \
  -H "facturadirecta-api-key: $fd_api_key" \
  "$fd_api_base/$fd_company_id/contacts?limit=5"

Para leer un contacto concreto, usa su ID:

curl -s \
  -H "facturadirecta-api-key: $fd_api_key" \
  "$fd_api_base/$fd_company_id/contacts/con_..."

Crear una factura de prueba#

Cuando ya puedas leer datos, prueba una operación de escritura en sandbox. Este ejemplo crea una factura completa mínima.

Crea un fichero invoice.json:

{
  "content": {
    "main": {
      "contact": "con_2e3f4a18-9b7c-4d6a-8e1f-5c2d3b4a7e9f",
      "date": "2026-05-13",
      "dueDate": "2026-06-12",
      "currency": "EUR",
      "docNumber": { "series": "F-##-" },
      "fiscalPosition": "general",
      "account": "700000",
      "theme": "default",
      "draft": true,
      "voided": false,
      "simplified": false,
      "lines": [
        {
          "account": "700000",
          "quantity": 1,
          "unitPrice": 100,
          "discount": 0,
          "discountRate": 0,
          "lineTotal": 100,
          "tax": ["S_IVA_21"],
          "text": "Servicios de consultoría"
        }
      ]
    }
  }
}

Envíalo a la API:

curl -s \
  -H "facturadirecta-api-key: $fd_api_key" \
  -H "Content-Type: application/json" \
  -d @invoice.json \
  "$fd_api_base/$fd_company_id/invoices"

Notas:

• Usa draft: true para que la factura sea provisional durante las pruebas.
• Sustituye contact, theme, account, tax y la serie por valores válidos de tu empresa.
• Si tu empresa usa TicketBAI o VeriFactu, revisa las guías específicas antes de crear facturas definitivas.

Errores comunes#

401 Unauthorized#

La API key no es válida o no se ha enviado. Comprueba:

• que la cabecera se llama facturadirecta-api-key;
• que la clave está copiada completa;
• que la clave no ha sido eliminada.

403 Forbidden#

La clave existe, pero no tiene permisos para la operación. Comprueba:

• que incluye el scope necesario, por ejemplo invoices:read para leer facturas;
• que el companyId corresponde a la empresa donde se creó la API key.

404 Not Found#

El recurso no existe o la URL no es correcta. Comprueba:

• que el companyId es correcto;
• que el path del endpoint existe;
• que el ID del recurso (inv_..., con_...) pertenece a esa empresa.

Ritmo de llamadas#

Cada empresa tiene un límite de peticiones por minuto según su plan (30 en Gratis, 60 en Bronce, 120 en Plata, 300 en Oro y 600 en Diamante). Cada respuesta lleva las cabeceras X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset; úsalas para espaciar las llamadas en cargas masivas. Ver Autenticación.

Siguientes pasos#

• Consulta la API Pública de FacturaDirecta para ver la visión general.
• Revisa Autenticación para API keys y OAuth2.
• Revisa Paginación y filtros estándar.
• Revisa Idempotencia y reintentos seguros antes de automatizar altas, cobros o una migración.
• Explora la referencia OpenAPI.
• Configura webhooks si tu integración necesita recibir cambios en tiempo real.