Factuarea API
FacturaE (B2G)

List invoice FACe submissions

Lists the FACe submission history of an invoice (flat array, newest included). Returns `data: []` when the invoice has never been submitted.

GET
/invoices/{invoice}/face-submissions

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

invoice*string

Response Body

application/json

application/json

application/json

application/json

application/json

import { Factuarea } from "@factuarea/sdk";const factuarea = new Factuarea({ apiKey: process.env.FACTUAREA_API_KEY! });// List endpoints return an async-iterable Page (cursors handled for you).for await (const item of await factuarea.invoices.faceSubmissions.list("01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01", { limit: 25 })) {  console.log(item.id);}
{
  "data": [
    {
      "id": "01972f4e-9c2b-7d3a-8e5f-1a2b3c4d5e6f",
      "object": "face_submission",
      "invoice_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8d01",
      "status": "submitted",
      "registry_number": "202600123456",
      "dir3_accounting_office": "E04921301",
      "dir3_managing_body": "E04921302",
      "dir3_processing_unit": "E04921303",
      "error_code": null,
      "error_message": null,
      "status_updated_at": "2026-06-11T10:30:00+00:00",
      "last_polled_at": null,
      "created_at": "2026-06-11T10:30:00+00:00"
    }
  ]
}

{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "No se ha proporcionado una API key válida en el header Authorization.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#missing_api_key",
    "request_id": "req_01HKQS5N8VR7QXJ9K3T6BWPMZA"
  }
}

{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_scope",
    "message": "Esta API key no tiene el scope requerido para esta operación.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#insufficient_scope",
    "request_id": "req_01HKQS5NBC3P8M1KX4V7SLNHQD"
  }
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Has excedido el rate limit de 60 peticiones por minuto. Reintenta tras 30 segundos.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#rate_limit_exceeded",
    "request_id": "req_01HKQS5NKW1C6W9T4G5H0JBZVL"
  }
}

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Ha ocurrido un error inesperado. Si persiste, contacta con soporte adjuntando el request_id.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#internal_error",
    "request_id": "req_01HKQS5NLX2D7X0U5H6J1KCAWM"
  }
}
GET

Retrieve a FACe submission

Retrieves a FACe submission by its `id` (UUID). The `status` field reflects the latest known FACe processing state (`submitted`, `registered_rcf`, `accounted`, `paid`, `rejected`, `cancellation_requested`, `cancelled`, `error`) — the system polls FACe periodically, so a plain GET is the way to track progress (there is no refresh endpoint in v1).

POST

Submit invoice to FACe

Submits an issued invoice to FACe (the Spanish B2G general entry point). Requires the client's three DIR3 codes and an active signing certificate; the FacturaE 3.2.2 XML is signed XAdES-EPES and presented through the FACe web service, returning the registry number. No request body: the invoice travels in the path and the DIR3 codes are read from the client. Test keys (`fact_test_`) simulate the submission (`FACE-SANDBOX-*` registry) without contacting FACe. Errors: 422 (`invoice_not_emittable_for_facturae`, `client_missing_dir3_codes`, `signing_certificate_required`), 409 `face_submission_already_exists` (an active submission already exists for the invoice), 502 `face_transmission_failed` (nothing is persisted when the FACe web service is down).