---
title: "Create one invoice (same validation as the web form)"
method: POST
path: "/api/invoices"
---

# Create one invoice (same validation as the web form)

`POST /api/invoices`

## Request

- Base URL: `https://declararfacil.com`
- URL: `https://declararfacil.com/api/invoices`
- Auth: HTTP bearer

## Request body

- InvoiceInput
  - `tipo` 'EMITIDA' | 'RECIBIDA', required: EMITIDA = the user issued it (income). RECIBIDA = the user received it (expense).
  - `numeroFactura` string, nullable
  - `fechaFactura` string, required: YYYY-MM-DD
  - `fechaOperacion` string, nullable: YYYY-MM-DD when it differs from fechaFactura
  - `nombreClienteProveedor` string, required: The other party (client for EMITIDA, supplier for RECIBIDA)
  - `nifClienteProveedor` string, nullable: NIF/CIF/NIE or EU VAT number, as printed
  - `direccionCliente` string, nullable
  - `paisProveedor` string, nullable: ISO 3166-1 alpha-2, e.g. ES, DE, US
  - `tipoOperacion` 'NACIONAL' | 'INTRACOMUNITARIA' | 'EXTRACOMUNITARIA'
  - `operacionB2B` boolean
  - `esAdquisicionIntracomunitaria` boolean
  - `esServicioNoSujeto` boolean
  - `baseImponible` number, required: Taxable base in EUR (sum of all bases if several rates; then tipoIVA is the main rate)
  - `tipoIVA` number, required: IVA rate in percent: 21, 10, 4 or 0
  - `cuotaIVA` number, required: Printed invoice VAT amount in EUR; keep printed zero for reverse charge
  - `tipoIVAAutorrepercutido` number, nullable: Applicable Spanish self-assessment rate, separately confirmed from the printed invoice rate. Never infer from printed 0%.
  - `fuenteTipoIVAAutorrepercutido` string, nullable: Basis for the applicable rate, e.g. confirmed tax classification and AEAT rule. Missing basis requires review.
  - `porcentajeDeduccionIVA` number, nullable: Independently confirmed VAT deduction percentage based on business use, valid evidence and applicable deduction rules. 0 means no deduction; null means unresolved. Independent of income-tax esDeducible.
  - `ivaAutorrepercutido` number, nullable: Server result: base * self-assessment rate / 100, rounded per invoice to EUR cents; never added to the printed invoice total
  - `tipoRetencion` number, nullable: IRPF withholding rate in percent, if the invoice shows one (e.g. 15 or 7)
  - `cuotaRetencion` number, nullable: IRPF withholding amount in EUR
  - `suplidos` number, nullable
  - `tipoRecargoEquivalencia` number, nullable
  - `cuotaRecargoEquivalencia` number, nullable
  - `claveRegimenEspecial` string, nullable
  - `descripcionOperacion` string, nullable: One line: what was sold or bought
  - `esFacturaRectificativa` boolean
  - `numeroFacturaRectificada` string, nullable
  - `totalFactura` number, required: Total to pay in EUR (base + IVA - retención + suplidos + recargo)
  - `categoria` string, nullable: Expense category for RECIBIDA (e.g. SOFTWARE, ALQUILER, SUMINISTROS, MATERIAL, SERVICIOS_PROFESIONALES, TRANSPORTE, OTROS)
  - `esDeducible` boolean
  - `notas` string, nullable
  - `confianzaOCR` number, nullable: Your own confidence 0..1 that every amount is read correctly
  - `source_file` string, nullable: Local file name, for the user's report only (never stored as a document)

## Response `200`

OK

## Other responses

- `401`: invalid_token: unknown or replaced token; start a new connection with POST /api/agent/v1/connect
- `402`: subscription_required: no active subscription; the body carries subscribe_url, steps, next_step and tell_the_user

---

[API](https://skmtc.dev/declararfacil/apis/declarar-facil-agent-api.md) · [All operations](https://skmtc.dev/declararfacil/apis/declarar-facil-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/declararfacil/apis/declarar-facil-agent-api/revisions/6d6837a48359?raw)