Conciliar amb la metadata de sistema

Tots els documents de Factuarea porten un objecte metadata de forma lliure on pots escriure el que necessitis. A les factures que Factuarea emet automàticament des d'un cicle de subscripció de Stripe, la plataforma escriu a més un grapat de claus de sistema que lliguen la factura al cobrament del qual va néixer: quina factura de Stripe, quina subscripció, quin període de facturació.

Aquestes claus són el que fa possible la conciliació sense mantenir la teva pròpia taula de correspondències. Fa temps que s'escriuen; aquesta pàgina és on queden documentades.

Les claus de sistema

Les claus opcionals no es materialitzen com a nul·les ni buides: quan el valor no aplica, la clau no s'escriu. És deliberat — una clau present amb valor buit semblaria una correlació que existeix però està en blanc, i qualsevol codi que la llegís hauria de distingir «sense subscripció» de «subscripció desconeguda». Comprova la presència de la clau, no el seu valor.

Les claus es llegeixen allà on sigui la factura: metadata forma part del recurs de factura, i torna com un objecte JSON ({} quan és buit).

Filtrar per metadata

Vuit llistats v1 accepten un filtre metadata:

La sintaxi és deepObject: metadata[clau]=valor, un paràmetre de consulta per parell.

• Els parells es combinen amb AND. Dos parells retornen els documents que compleixen tots dos.
• Coincidència exacta al valor; no hi ha coincidència parcial ni per prefix.
• Fins a 50 parells per petició; a partir d'aquí retorna parameter_invalid_range.
• Les claus han d'encaixar a [A-Za-z0-9_.-] i mesurar entre 1 i 64 caràcters; qualsevol altra cosa retorna parameter_invalid_enum.
• El filtre queda fora del contracte {operator, value} dels filtres de columna, així que no existeix la forma metadata[clau][eq]. metadata[clau]=valor és tota la sintaxi.

Recepta: totes les factures d'una subscripció

La conciliació que necessites quan un client et demana totes les factures del seu pla, o quan tanques l'any d'un subscriptor:

curl -G https://api.factuarea.com/v1/invoices \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  --data-urlencode "metadata[stripe_subscription_id]=sub_1QRstuVWXYZabcde" \
  --data-urlencode "limit=100"

{
  "data": [
    {
      "id": "0192f3a4-7b2c-7c1d-9e8f-1a2b3c4d5e6f",
      "object": "invoice",
      "number": "2026/0184",
      "total": "49.90",
      "currency": "EUR",
      "metadata": {
        "stripe_invoice_id": "in_1QRstuVWXYZabcde",
        "billing_reason": "subscription_cycle",
        "stripe_subscription_id": "sub_1QRstuVWXYZabcde",
        "period_start": "2026-07-01",
        "period_end": "2026-08-01"
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

El llistat es pagina per cursor com tots els altres: continua llegint mentre has_more valgui true, tornant next_cursor a starting_after. Vegeu Paginació.

Recepta: les factures d'un període de facturació

Dos parells, combinats amb AND: la subscripció i el primer dia del període. És la consulta que respon a «s'ha facturat el cicle de juliol?».

curl -G https://api.factuarea.com/v1/invoices \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  --data-urlencode "metadata[stripe_subscription_id]=sub_1QRstuVWXYZabcde" \
  --data-urlencode "metadata[period_start]=2026-07-01"

Com que period_start i period_end són dates exactes en UTC, filtra pel límit del període en comptes de per un rang — el valor de la metadata és el dia que Stripe reporta per al cicle, no un mes de calendari local. Per escombrar un mes sencer de cicles de totes les subscripcions, treu el parell de la subscripció i consulta metadata[period_start] tot sol.

Un array data buit per a un període que esperaves facturat és un senyal real, no un error del filtre. És exactament el cas que explica la safata d'esdeveniments d'integració: obre-la filtrada per provider=stripe i status=skipped i el motiu de descart tipat et dirà si el cicle es va saltar perquè l'auto-facturació estava apagada, perquè el cicle no portava import, o per una altra cosa — i si el pots reprocessar.

Relacionat

• Auto-facturació amb Stripe — com s'emeten, per començar, les factures que aquestes claus descriuen.
• Safata d'esdeveniments d'integració — per què un cicle que esperaves no va produir mai factura.
• Etiquetes i camps personalitzats — escriure i consultar les teves pròpies claus de metadata.