Etiquetes i camps personalitzats

Classifica documents amb tags i adjunta custom_fields tipats. Filtra llistats per tag. En què es diferencien de metadata.

Dos camps transversals et permeten classificar i enriquir els documents amb les teves pròpies dades de negoci: tags (etiquetes de classificació lliures per les quals pots filtrar els llistats) i custom_fields (una llista ordenada de parells tipats {field, value}). Tots dos s'estableixen a create/update i es retornen en cada lectura.

Camp	Forma	Límits	Filtrable	Recursos
`tags`	array de slugs	≤ 30, cadascun ≤ 40 caràcters	Sí (`?tags=`, `?tags[in]=`)	invoices, quotes, proformas, delivery_notes, purchase_invoices, recurring_invoices, products
`custom_fields`	array ordenat de `{field, value}`	≤ 50 entrades	No	invoices, quotes, proformas, delivery_notes, purchase_invoices, recurring_invoices

Etiquetes

Un tag és un slug en minúscula que compleix [a-z0-9-] — només lletres, dígits i guions. Cada tag mesura com a màxim 40 caràcters, i un document porta com a màxim 30 tags. Passa'ls com un array JSON de strings en crear o actualitzar:

curl -X POST https://api.factuarea.com/v1/invoices \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",
    "series_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02",
    "issued_on": "2026-05-15",
    "due_on": "2026-06-15",
    "tags": ["consultoria", "cliente-vip"],
    "lines": [
      { "description": "Monthly service", "quantity": 1, "unit_price": 99.00, "tax_rate_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a03" }
    ]
  }'

Els tags es retornen com un array pla en cada lectura (buit [] quan no n'hi ha cap):

{
  "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0b",
  "number": "F-2026-0042",
  "tags": ["consultoria", "cliente-vip"]
}

tags és una substitució completa en actualitzar: enviar "tags": ["a"] reemplaça tot el conjunt, no l'afegeix. Per afegir un tag, envia la llista sencera incloent-hi els existents. Per buidar-los, envia [].

Filtrar per tag

Els endpoints de llistat accepten dos paràmetres de query per filtrar per tag — tria'n un:

Paràmetre	Semàntica	Exemple
`tags`	Coincidència exacta amb un únic slug.	`?tags=cliente-vip`
`tags[in]`	Llista separada per comes, semàntica OR — coincideix amb els documents que portin qualsevol dels slugs.	`?tags[in]=cliente-vip,moroso`

# Totes les factures etiquetades amb "cliente-vip"
curl -G https://api.factuarea.com/v1/invoices \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  --data-urlencode "tags=cliente-vip"

# Factures etiquetades amb "cliente-vip" O "moroso"
curl -G https://api.factuarea.com/v1/invoices \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  --data-urlencode "tags[in]=cliente-vip,moroso"

El filtre per tag està disponible a invoices, quotes, proformas, delivery_notes, purchase_invoices i recurring_invoices. Es combina amb la resta de filtres i amb la paginació per cursor.

Camps personalitzats

custom_fields és un array ordenat de parells tipats {field, value}, per a dades de negoci que vulguis mostrar al costat del document (centre de cost, número de comanda, codi de projecte…). Fins a 50 entrades; cada field és un string no buit de com a màxim 60 caràcters i cada value és un string de com a màxim 500 caràcters. L'ordre es conserva exactament tal com l'envies.

curl -X POST https://api.factuarea.com/v1/invoices \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",
    "series_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02",
    "issued_on": "2026-05-15",
    "due_on": "2026-06-15",
    "custom_fields": [
      { "field": "centro_coste", "value": "CC-2026-001" },
      { "field": "numero_pedido", "value": "PO-2026-0042" }
    ],
    "lines": [
      { "description": "Monthly service", "quantity": 1, "unit_price": 99.00, "tax_rate_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a03" }
    ]
  }'

Igual que tags, l'array sencer és una substitució total en actualitzar, i es retorna en ordre en cada lectura (buit [] quan no n'hi ha cap).

Camps personalitzats enfront de metadata

Tant custom_fields com metadata porten dades teves, però serveixen per a propòsits diferents — no facis servir el que no toca.

Fes servir custom_fields per a dades de negoci ordenades i tipades que l'usuari veu al document. Fes servir metadata per a un mapa desordenat clau→valor de dades d'integració opaques (codis d'ERP, referències de la teva pròpia comptabilitat) que ningú llegeix visualment. Un document pot portar tots dos.

	`custom_fields`	`metadata`
Forma	Llista ordenada de `{field, value}`	Mapa desordenat `key → value`
Ordre	Es conserva	Cap
Límit	≤ 50 entrades	≤ 50 claus
Clau	`field`, 1–60 caràcters	clau del mapa
Valor	string ≤ 500 caràcters	string ≤ 500 caràcters
Intenció	Camps de negoci que l'usuari veu	Dades d'integració opaques
Recursos	Els sis recursos de document	Tots els recursos

Els recursos mestres (clients, suppliers) no tenen custom_fields tipats — fes servir el seu metadata com a magatzem de camps personalitzats sense tipar. Els products accepten tags però no custom_fields.

Exemples

import os, requests

base = 'https://api.factuarea.com/v1'
headers = {'Authorization': f"Bearer {os.environ['FACTUAREA_API_KEY']}"}

# Create an invoice with tags + custom_fields
resp = requests.post(f'{base}/invoices', headers=headers, json={
    'client_id': '01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01',
    'series_id': '01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02',
    'issued_on': '2026-05-15',
    'due_on': '2026-06-15',
    'tags': ['consultoria', 'cliente-vip'],
    'custom_fields': [
        {'field': 'centro_coste', 'value': 'CC-2026-001'},
        {'field': 'numero_pedido', 'value': 'PO-2026-0042'},
    ],
    'lines': [
        {'description': 'Monthly service', 'quantity': 1,
         'unit_price': 99.00, 'tax_rate_id': '01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a03'},
    ],
})
resp.raise_for_status()

# List invoices tagged "cliente-vip" OR "moroso"
rows = requests.get(f'{base}/invoices', headers=headers,
                    params={'tags[in]': 'cliente-vip,moroso'}).json()['data']
print(len(rows), 'matching invoices')

const base = 'https://api.factuarea.com/v1';
const headers = {
  Authorization: `Bearer ${process.env.FACTUAREA_API_KEY}`,
  'Content-Type': 'application/json',
};

// Create an invoice with tags + custom_fields
await fetch(`${base}/invoices`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    client_id: '01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01',
    series_id: '01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02',
    issued_on: '2026-05-15',
    due_on: '2026-06-15',
    tags: ['consultoria', 'cliente-vip'],
    custom_fields: [
      { field: 'centro_coste', value: 'CC-2026-001' },
      { field: 'numero_pedido', value: 'PO-2026-0042' },
    ],
    lines: [
      { description: 'Monthly service', quantity: 1,
        unit_price: 99.0, tax_rate_id: '01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a03' },
    ],
  }),
});

// List invoices tagged "cliente-vip" OR "moroso"
const url = new URL(`${base}/invoices`);
url.searchParams.set('tags[in]', 'cliente-vip,moroso');
const { data } = await fetch(url, { headers }).then((r) => r.json());
console.log(data.length, 'matching invoices');

# Create an invoice with tags + custom_fields
curl -s -X POST https://api.factuarea.com/v1/invoices \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",
    "series_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02",
    "issued_on": "2026-05-15",
    "due_on": "2026-06-15",
    "tags": ["consultoria", "cliente-vip"],
    "custom_fields": [
      { "field": "centro_coste", "value": "CC-2026-001" },
      { "field": "numero_pedido", "value": "PO-2026-0042" }
    ],
    "lines": [
      { "description": "Monthly service", "quantity": 1, "unit_price": 99.00, "tax_rate_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a03" }
    ]
  }' | jq '{id, tags, custom_fields}'

# List invoices tagged "cliente-vip" OR "moroso"
curl -s -G https://api.factuarea.com/v1/invoices \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  --data-urlencode "tags[in]=cliente-vip,moroso" | jq '.data | length'