Terceros y productos

Los terceros son tus clientes y proveedores. Los productos son los artículos que facturas. Desde la API puedes buscar terceros, darlos de alta o actualizarlos, y consultar tus productos.

Todas las llamadas usan la URL base https://app.faxtal.com/api/v1.1 y la cabecera X-API-Key (ver Autenticación).

Operación	Scope de la API key
Buscar terceros y productos	invoices:read
Alta o actualización de terceros	parties:write

Sin el scope necesario, la API responde 403 con el código scope_missing.

---

De dónde salen

• Terceros: se registran solos al guardar una factura válida, emitida o recibida. La contraparte (el cliente en una emitida, el proveedor en una recibida) se identifica por su NIF. Las facturas simplificadas y las que no traen el NIF de la contraparte no registran tercero. También puedes darlos de alta tú.
• Productos: se alimentan de las líneas con article_code de las facturas emitidas sin errores. Si el mismo article_code vuelve a aparecer, se queda la versión más reciente. La API no permite crear ni editar productos.

Una factura no se enlaza con un tercero por su identificador: en customer o supplier envías los datos de la parte (ver Formato canónico).

---

Buscar terceros

GET /api/v1.1/third-parties

Parámetro	Descripción
search	Texto que se busca dentro de name y de tax_id. Hasta 200 caracteres.
role	customer o supplier. Sin él, devuelve ambos.
limit	De 1 a 200. Por defecto, 50.
offset	Desplazamiento. Por defecto, 0.

curl -G "https://app.faxtal.com/api/v1.1/third-parties" \
  -H "X-API-Key: fctXXXXXXXX_YYYYYYYYYYYYYYYY" \
  --data-urlencode "search=Cliente Prueba" \
  -d role=customer

Respuesta 200, resumida:

{
  "items": [
    {
      "id": 1234,
      "tax_id": "B10000016",
      "country_code": "ES",
      "person_type_code": "J",
      "name": "Cliente Prueba S.L.",
      "trade_name": null,
      "is_customer": true,
      "is_supplier": false,
      "eu_vat_id": null,
      "primary_address": null,
      "primary_contact": null,
      "created_at": "2026-11-02T09:15:00",
      "updated_at": "2026-11-02T09:15:00"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Los resultados salen ordenados por name y tax_id. Campos principales de cada tercero:

Campo	Descripción
id	Identificador del tercero. Es el third_party_id que devuelve el alta.
tax_id, country_code	NIF y país. Juntos identifican al tercero.
person_type_code	F (persona física) o J (persona jurídica).
name, trade_name	Razón social o nombre, y nombre comercial.
first_name, first_surname, second_surname	Nombre y apellidos, en personas físicas.
is_customer, is_supplier	Si es cliente, proveedor o ambos.
eu_vat_id	NIF-IVA intracomunitario.
vies_status, vies_checked_at, vies_consultation_number, vies_name	Resultado de la comprobación del NIF-IVA en VIES, si se ha hecho.
attachment_formats	Formatos que se adjuntan al enviar facturas a este tercero.
primary_address, primary_contact	Dirección y contacto principales, o null.
created_at, updated_at	Fechas de alta y de última modificación.

---

Dar de alta o actualizar un tercero

PUT /api/v1.1/third-parties

Campo	Obligatorio	Descripción
tax_id	Sí	NIF. De 1 a 32 caracteres.
name	Sí	Razón social o nombre. De 1 a 255 caracteres.
country_code	No	País, dos letras. Por defecto, ES.
person_type_code	No	F o J.
trade_name	No	Nombre comercial. Hasta 255 caracteres.
is_customer	No	Si es cliente.
is_supplier	No	Si es proveedor.
eu_vat_id	No	NIF-IVA intracomunitario. Hasta 32 caracteres.

curl -X PUT "https://app.faxtal.com/api/v1.1/third-parties" \
  -H "X-API-Key: fctXXXXXXXX_YYYYYYYYYYYYYYYY" \
  -H "Content-Type: application/json" \
  -d '{
    "tax_id": "B10000016",
    "country_code": "ES",
    "name": "Cliente Prueba S.L.",
    "person_type_code": "J",
    "is_customer": true
  }'

Respuesta 200:

{
  "third_party_id": 1234,
  "created": true
}

Cómo funciona:

• La clave es tax_id más country_code. Si no existe un tercero con esa clave, se crea (created: true). Si existe, se actualiza (created: false).
• En un alta, si no indicas el rol, el tercero queda como cliente (is_customer: true, is_supplier: false).
• En una actualización, solo cambian los campos que envías. El NIF y el país no se modifican.
• Lo que guardas por aquí prevalece: las facturas que entren después no sobrescriben esos datos.
• No gestiona direcciones ni contactos.

Errores

HTTP	code	Causa
422	request_validation_error	Falta tax_id o name, un valor supera su longitud, person_type_code no es F ni J, o hay un campo que no está en la tabla. El detalle trae errors.
403	scope_missing	La API key no tiene parties:write.

---

Consultar productos

GET /api/v1.1/products

Parámetro	Descripción
search	Texto que se busca dentro de article_code y de name. Hasta 200 caracteres.
limit	De 1 a 200. Por defecto, 50.
offset	Desplazamiento. Por defecto, 0.

curl -G "https://app.faxtal.com/api/v1.1/products" \
  -H "X-API-Key: fctXXXXXXXX_YYYYYYYYYYYYYYYY" \
  -d search=CONSULT

Respuesta 200, resumida:

{
  "items": [
    {
      "id": 88,
      "article_code": "CONSULT-SENIOR",
      "name": "Consultoría senior",
      "item_type": "service",
      "unit_of_measure": "HUR",
      "price_mode": "without_tax",
      "unit_price": 100.0,
      "tax_treatment_code": "TAXABLE_NON_EXEMPT",
      "tax_output_code": "IVA_G",
      "tax_withheld_code": null,
      "last_invoice_public_id": "00000000-0000-0000-0000-000000000001",
      "last_issue_date": "2026-11-02",
      "created_at": "2026-11-02T09:15:00",
      "updated_at": "2026-11-02T09:15:00"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Los resultados salen ordenados por article_code. Campos de cada producto:

Campo	Descripción
id	Identificador del producto.
article_code	Código del artículo, el mismo que el article_code de las líneas.
name	Nombre.
item_type	Tipo de artículo (bien o servicio).
unit_of_measure	Unidad de medida.
price_mode	Si unit_price incluye el impuesto (with_tax) o no.
unit_price, discount_rate, charge_rate	Precio unitario y descuento o recargo de línea.
tax_treatment_code	Tratamiento fiscal.
tax_output_code, tax_withheld_code	Código del tipo de impuesto y del tipo de retención (por ejemplo, IVA_G).
exemption_reason_code, exemption_reason_text, non_taxable_reason, tax_regime_key	Exención, no sujeción y régimen especial.
fiscal_classification	Clasificación fiscal que deduce el sistema.
last_source, last_invoice_public_id, last_issue_date	Origen y última factura que actualizó el producto.
created_at, updated_at	Fechas de alta y de última modificación.

El producto guarda el código del tipo de impuesto (tax_output_code). En una línea de factura se envía el porcentaje (tax_output_rate), nunca el código. La correspondencia está en la tabla de tipos del Formato canónico.

Errores

HTTP	code	Causa
402	feature_outside_plan	El plan de la empresa no incluye el catálogo de productos.
403	scope_missing	La API key no tiene invoices:read.

---

Ver también

• Formato canónico: partes (customer, supplier) y líneas.
• Facturas emitidas y Facturas recibidas.
• Errores: formato común de las respuestas de error.
• Referencia interactiva.