NewProvince is only required for addresses in Spain
BeeL
Get startedMulti-NIFVeriFactuRulesStripeAPI referenceChangelog

Where the contract and the API disagreed, they now agree

A check of the published contract against the live API found a dozen differences. A few were fixed in the API, and the rest in the contract.

ChangelogFixed

We replayed the published contract against the live API and wrote down every place where they disagreed. Where the API was wrong, the API changed. The first four highlights are those, and they are the only ones where a response differs from before. Where the document was wrong, the document changed and the server behaves as it always did.

What else changed

  • logo_url on a company is an absolute URL. GET /v1/companies/{company_id} returned a storage path for a logo uploaded through the logo endpoint. It now returns the same fetchable URL as the invoice-customization resource and an invoice's issuer.logo_url.
  • A number field that receives text answers 400 INVALID_JSON_FORMAT with details filled in: field, invalid_value and expected_format (number or integer). It used to come back with details: {}.
  • A deprecated route that rejects an unknown query parameter still sends Deprecation and Sunset on that 400, like on any other answer from it.
  • A property that breaks two rules at once gets one stable message with both reasons, instead of one of the two, picked differently on identical calls.
  • Contract corrections, server unchanged: GET /v1/accounts/{account_id}/companies is always paginated and always carries pagination. A value outside an enum in a body answers 422 VALIDATION_ERROR with allowed_values, not 400. POST …/customers can answer 422 NIF_NOT_IN_CENSUS. A body property the operation does not declare is ignored without a warning.
  • 404 and 409 name what failed. The contract now lists the codes the API already returned, such as INVOICE_NOT_FOUND, CLIENT_NOT_FOUND, CLIENT_DUPLICATE and ENDPOINT_NOT_FOUND, in place of a generic NOT_FOUND or CONFLICT that it never sent.

Where to go next

Handling errorsINVALID_JSON_FORMATList the companies of an account

A simplified invoice can no longer name an identified recipient

Creating or updating a `SIMPLIFIED` invoice whose recipient has a NIF or an alternative identifier now answers `400 SIMPLIFIED_INVOICE_FORBIDS_IDENTIFIED_RECIPIENT`. Issue it as `STANDARD`.

Export lines take regime 02 on their own

A VAT line exempt under art. 21 or 22 that arrives with `regime_key: "01"` is stored with `"02"`, instead of being refused by AEAT after issue.