Primeros pasos

Esta guía te lleva de cero a tu primera llamada autenticada y a validar una factura sin guardarla.

1. Comprueba los requisitos

Tu plan incluye la API. Si no la incluye, cualquier llamada autenticada responde 402 con feature_outside_plan.
Tienes el rol Propietario o Admin en la empresa. Son los roles que pueden crear API keys.

2. Crea una API key

La clave se crea en la aplicación, en Configuración → API Keys. Los pasos están en Crear y gestionar API keys.

Copia la clave al crearla: no se vuelve a mostrar.
Da acceso completo a los datos de la empresa por la API. Guárdala como una contraseña.

En los ejemplos, la clave va en una variable de entorno de tu equipo. El valor es ficticio:

export FAXTAL_API_KEY='fctXXXXXXXX_YYYYYYYYYYYYYYYY'

3. Usa la URL base

https://app.faxtal.com/api/v1.1

No hay entorno de pruebas publicado. Todas las llamadas trabajan con los datos reales de tu empresa: lo que guardas o emites queda registrado. Para probar una factura sin guardar nada, usa las operaciones de validación del paso 6.

4. Comprueba que la API responde

GET /api/v1.1/health no pide API key.

curl -s https://app.faxtal.com/api/v1.1/health

Respuesta 200:

{ "status": "ok" }

5. Haz tu primera llamada autenticada

GET /api/v1.1/company devuelve la empresa a la que pertenece la clave. No exige ningún permiso concreto.

curl -s https://app.faxtal.com/api/v1.1/company \
  -H "X-API-Key: $FAXTAL_API_KEY"

Respuesta 200:

{
  "id": "AbCd1234",
  "name": "Empresa Demo",
  "legal_name": "Empresa Demo S.L.",
  "tax_id": "B10000008",
  "country": "ES",
  "currency": "EUR",
  "contact_name": "Ana Pérez",
  "contact_email": "facturacion@empresa-demo.es",
  "contact_phone": "910000000",
  "address": {
    "line": "Calle Mayor 1",
    "post_code": "28001",
    "town": "Madrid",
    "province_code": "ES-M",
    "province_id": 28
  },
  "is_active": true,
  "person_type_code": "J",
  "default_tax_group": "IVA",
  "plan": "business",
  "features": ["sii", "products"],
  "fiscal_systems": {
    "ticketbai_active": false,
    "verifactu_in_plan": true,
    "sii_in_plan": true
  }
}

Si falla:

Código	`code`	Qué revisar
`401`	`unauthorized`	Falta la cabecera `X-API-Key`, o la clave está mal copiada, revocada o caducada.
`402`	`feature_outside_plan`	El plan de la empresa no incluye la API.
`403`	`ip_forbidden`	La clave solo admite ciertas IP y llamas desde otra.
`429`	`rate_limited`	Has superado el límite de peticiones. Espera los segundos que indica `Retry-After`.

6. Valida una factura sin guardarla

POST /api/v1.1/issued-invoices/validate recibe una factura en formato json_1_1 y devuelve si es válida. No guarda nada, no asigna número y no envía nada a Hacienda.

curl -s -X POST https://app.faxtal.com/api/v1.1/issued-invoices/validate \
  -H "X-API-Key: $FAXTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d @factura.json

Respuesta 200 resumida, con un error:

{
  "is_valid": false,
  "errors": [
    {
      "source": "schema",
      "code": "inferred_fields_not_allowed",
      "message": "El payload incluye campos que el sistema infiere y que no deben enviarse. …",
      "path": "/invoice/lines/0/tax_category_code",
      "extra": null,
      "severity": "error"
    }
  ],
  "data": null
}

is_valid: true significa que la factura se puede guardar y emitir tal cual.
Cada error trae code y path, la ruta del campo dentro del JSON.
Para recibidas, usa POST /api/v1.1/received-invoices/validate.

Siguientes pasos

Autenticación: permisos, límites de uso y buenas prácticas.
Conceptos: estados, series y numeración, idempotencia.
Borradores y Facturas emitidas: guardar y emitir tu primera factura.