Factuarea API
FacturaE (B2G)

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).

POST
/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

application/json

import { Factuarea } from "@factuarea/sdk";const factuarea = new Factuarea({ apiKey: process.env.FACTUAREA_API_KEY! });const result = await factuarea.invoices.faceSubmissions.submit("01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01");
{
  "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": "idempotency_error",
    "code": "idempotency_key_reused",
    "message": "La cabecera `Idempotency-Key` ya se usó con un body distinto. Usa una clave nueva o reenvía exactamente el mismo body.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#idempotency_key_reused",
    "request_id": "req_01HKQS5NHT9A4U7R2E3F8GZWTJ"
  }
}

{
  "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

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

Download FacturaE XML

Streams the FacturaE **3.2.2** XML for the invoice (B2G compliance), XSD-conformant with full tax breakdown. When the company has an active signing certificate the body is signed **XAdES-EPES** (Facturae v3.1 signature policy) and the filename is `.xsig`; without a certificate the XML is returned unsigned as `.xml`. The `X-Facturae-Signed: true|false` response header tells both cases apart. Draft invoices return 422 `invoice_not_emittable_for_facturae`.