Skip to main content

Quickstart

Get up and running with FiscalAPI in under 5 minutes. This guide uses curl -- no SDK required.

Base URL​

https://api.fiscalapi.com

For local development:

http://localhost:8080

1. Create an account​

Create an account to receive your API key. This is a public endpoint -- no authentication required.

curl -X POST https://api.fiscalapi.com/v1/accounts \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "billing_email": "admin@acme.com"
  }'

Response:

{
  "account": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "name": "Acme Corp",
    "billing_email": "admin@acme.com",
    "status": "active",
    "created_at": "2026-03-08T12:00:00Z"
  },
  "api_key": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key_prefix": "fsk_test_",
    "key": "fsk_test_abc123def456...",
    "environment": "test",
    "created_at": "2026-03-08T12:00:00Z"
  }
}
Save your API key

The plaintext API key is returned only on creation and cannot be retrieved again. Store it securely.

2. Create a location​

Use your API key to create a merchant location. Here's a Spanish location with TicketBAI:

curl -X POST https://api.fiscalapi.com/v1/locations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fsk_test_abc123def456..." \
  -d '{
    "name": "Madrid Office",
    "country": "ES",
    "address": "Calle Gran Vía 1, 28013 Madrid",
    "tax_id": "B12345674",
    "country_config": {
      "system": "ticketbai",
      "territory_code": "48"
    }
  }'

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "account_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "name": "Madrid Office",
  "country": "ES",
  "address": "Calle Gran Vía 1, 28013 Madrid",
  "tax_id": "B12345674",
  "country_config": {
    "system": "ticketbai",
    "territory_code": "48"
  },
  "status": "active",
  "created_at": "2026-03-08T12:00:00Z",
  "updated_at": "2026-03-08T12:00:00Z"
}

3. List your locations​

curl https://api.fiscalapi.com/v1/locations \
  -H "Authorization: Bearer fsk_test_abc123def456..."

Response:

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Madrid Office",
      "country": "ES",
      "status": "active"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

4. Update a location​

curl -X PATCH https://api.fiscalapi.com/v1/locations/550e8400-e29b-41d4-a716-446655440000 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fsk_test_abc123def456..." \
  -d '{
    "name": "Madrid HQ"
  }'

5. Delete a location​

curl -X DELETE https://api.fiscalapi.com/v1/locations/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer fsk_test_abc123def456..."

Returns 204 No Content on success.

5. Submit a transaction​

Submit a sale for fiscalization. FiscalAPI never blocks the cash register -- the response is always 201 Created, and fiscalization happens inline or asynchronously.

curl -X POST https://api.fiscalapi.com/v1/transactions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fsk_test_abc123def456..." \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "location_id": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2026-03-09T14:30:00Z",
    "items": [
      {"description": "Café con leche", "quantity": 2, "unit_price": 2.50, "tax_rate": 0.21},
      {"description": "Tostada", "quantity": 1, "unit_price": 3.00, "tax_rate": 0.21}
    ],
    "pretax_amount": 6.61,
    "tax_amount": 1.39,
    "total_amount": 8.00,
    "currency": "EUR",
    "payment_method": "card"
  }'

Response:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "sale",
  "status": "pending",
  "amount": 800,
  "currency": "EUR",
  "environment": "test",
  "created_at": "2026-03-09T14:30:01Z"
}

6. Check transaction status​

Poll for the fiscalization result:

curl https://api.fiscalapi.com/v1/transactions/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer fsk_test_abc123def456..."

Response (once fiscalized):

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "success",
  "fiscal_id": "TBAI-12345678",
  "environment": "test",
  "submitted_at": "2026-03-09T14:30:02Z",
  "completed_at": "2026-03-09T14:30:03Z"
}
Use webhooks instead of polling

Configure a webhook to receive fiscalization.completed events instead of polling for status.

Next steps​