Skip to Content

Add a product

POST
/v1/ec/products

Adds a product to the catalog. Its line fields are named as a document's line names them, so a sale copies them into the line it issues: description, code, auxiliary_code, unit, taxes and additional_info, with unit_price worked out from price_with_iva.

Authorization

headerAuthorizationBearer <token>

Your API key, which acts for the one business it was created for: fb_live_… keys work at api.fiscalbase.io and issue in live, and fb_sandbox_… keys work at api-sandbox.fiscalbase.io and issue in sandbox, on the simulated SRI. A key sent to the other host is refused with api_key_wrong_host, which names its host.

Header Parameters

idempotency-key?string

Send the same key to retry safely: a repeat of the same request answers what the first answered, without doing it again. Keys are scoped to your key's business and environment; the same key with another request is 409 idempotency_key_reused.

Length1 <= length <= 255
Fiscalbase-Environment?string

The environment the call acts in. Required with a person's session; a key's own environment is the one that counts, so a key may leave it out, and naming another is 422 environment_mismatch.

Value in"sandbox""test""live"
Fiscalbase-Business?string

The business the call acts for. With a person's session, the one the call is about (without it, a call about one business is 422 business_required and a list covers every business of the organization); a key acts for its own, so naming another is 422 business_mismatch.

Formatuuid
Fiscalbase-Channel?string

Which of Fiscalbase's own integrations a key's call comes from, recorded as the channel of the documents it issues: a record, not a permission. Without it, api. A person's call is always console.

Value in"api""mcp"
Fiscalbase-Agent?string

The AI agent a key's call comes from, as its client names itself (the MCP server sets it); recorded with the request and shown in the console's request log.

Request Body

application/json
  1. body
description*string
Match^[^\n\r]*$
Length1 <= length <= 300
price_with_iva?string

What one unit costs on the shelf, IVA included, as a decimal string with cents. The line's unit_price is this without the IVA. The ICE and IRBPNR a line carries are charged on top. Needed unless sold_by is open_price, where the cashier types the price and this is only the one proposed.

Match^\d+(\.\d{1,2})?$
sold_by?string

unit: by the piece. weight: by weight or volume, the quantity a decimal and unit what it is measured in. open_price: at a price typed at the counter.

Default"unit"
Value in"unit""weight""open_price"
barcode?string

The code printed on the package or the shelf, up to 50 characters, unique among the business's products for sale in the environment. One of 8, 12, 13 or 14 digits is an EAN or a UPC and must end in its check digit.

Match^[^\n\r]*$
Length1 <= length <= 50
code?string

Main code of the product or service.

Match^[^\n\r]*$
Length1 <= length <= 25
auxiliary_code?string

Auxiliary code. For construction materials, its code from tabla 31; for commercial transport, the one from tabla 32.

Match^[^\n\r]*$
Length1 <= length <= 25
unit?string

Unit of measure.

Match^[^\n\r]*$
Length1 <= length <= 50
taxes*array<||>

The line's taxes by type: one iva, and at most one ice and one irbpnr.

additional_info?array<>
Itemsitems <= 3
Default[]
category_id?string

A product category of the same business and environment.

Formatuuid
favorite?boolean

Whether it shows on the sale screen's first page.

Defaultfalse
position?integer

Where it sits among the favourites, from the smallest.

Range0 <= value <= 1000000
Default0

Response Body

Added

application/json
  1. response
id*string
Formatuuid
object*"product"
Value in"product"
business_id*string
Formatuuid
environment*string
Value in"sandbox""test""live"
description*string

What the line says it sells, and what the catalog shows.

price_with_iva*|

What one unit costs on the shelf, IVA included. null for a product sold at an open_price that has none proposed. The ICE and IRBPNR a line carries are charged on top.

unit_price*|

The line's unit_price for this product: price_with_iva without its IVA, to six decimals. null when there is no price.

sold_by*string
Value in"unit""weight""open_price"
barcode*string|null
code*|

The line's code: the product's main code.

auxiliary_code*|

The line's auxiliary_code.

unit*|

The line's unit of measure.

taxes*array<||>

The line's taxes: one iva, and at most one ice and one irbpnr.

additional_info*array<>

The line's additional_info.

category_id*|
Formatuuid
favorite*boolean
position*integer
image*|null
archived_at*|

When it was archived: an archived product is out of the lists, the barcode lookup and the sale, and its barcode is free for another.

Formatdate-time
created_at*string
Formatdate-time
updated_at*string
Formatdate-time
Example Request
curl -X POST 'https://api.fiscalbase.io/v1/ec/products' \
  -H 'Content-Type: application/json' \
  -d '{
  "description": "string",
  "taxes": [
    {
      "type": "iva",
      "rate": "iva_15"
    }
  ]
}'
Example Response
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "object": "product",
  "business_id": "f59fcbb7-848d-4242-af07-a8bb7e3ab37c",
  "environment": "sandbox",
  "description": "string",
  "price_with_iva": "string",
  "unit_price": "string",
  "sold_by": "unit",
  "barcode": "string",
  "code": "string",
  "auxiliary_code": "string",
  "unit": "string",
  "taxes": [
    {
      "type": "iva",
      "rate": "iva_15"
    }
  ],
  "additional_info": [
    {
      "name": "string",
      "value": "string"
    }
  ],
  "category_id": "8de4c9fd-61a4-4c0b-bf88-0ed3a0fe3fa2",
  "favorite": true,
  "position": 0,
  "image": {
    "url": "http://example.com",
    "width": 0,
    "height": 0
  },
  "archived_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}