REST API v1

API reference

Every version 1 endpoint with its parameters, request and response examples, scopes, errors and webhook events.

Base URLEach shop runs the API on its own domain: https://<your-domain>/api/v1. Your shop's URL is shown in Developers / API; the examples use https://your-shop.example.

Authentication

Send the key in the Authorization: Bearer pt_live_… header (or X-Api-Key). pt_test_… keys can read, but any operation with side effects answers 403 test_key_forbidden. To try writes, acceptances, invoices and messages risk-free use the sandbox: https://demo.programa-taller.es/desarrolladores-sandbox (fictitious data, nothing is really sent).

Conventions

ISO 8601 UTC dates; EUR amounts with two decimals and currency: "EUR"; integer ids; stable snake_case field names. Workshop staff only appear as { id, name }.

Pagination

Lists return { data, next_cursor, has_more }. Fetch the next page by repeating the call with ?cursor=<next_cursor>. limit ranges 1–200 (default 50).

Error format

{
  "error": {
    "code": "insufficient_scope",
    "message": "The API key lacks the «budgets:read» scope."
  }
}
HTTPCodeMessage
401missing_api_keyMissing API key: send it in the Authorization: Bearer pt_… or X-Api-Key header.
401invalid_api_keyThe API key is not valid for this instance.
401revoked_api_keyThe API key has been revoked.
401expired_api_keyThe API key has expired.
403ip_not_allowedThe source IP address is not on this key's allow list.
403insufficient_scopeThe API key lacks the scope required for this operation.
403test_key_forbiddenA test key (pt_test_) cannot perform operations with side effects: use a live key.
429rate_limitedYou have exceeded this key's request limit. Wait and retry.
503instance_rate_limitedThe instance is receiving too many API requests right now. Retry in a few seconds.
429plan_quota_exceededThe workshop's API plan daily request quota is used up. It resets at 00:00 UTC; for more volume, upgrade the plan.
403plan_scope_not_allowedThe workshop's API plan does not include this scope. Upgrade the plan to use it.
400bad_requestThe request is not valid.
404not_foundResource not found.
502upstream_errorAn external service rejected the operation.
500internal_errorInternal error.
422validation_errorThe request body is not valid: check the «fields» list.
400idempotency_key_requiredMissing Idempotency-Key header (required on every POST; 8 to 255 visible characters).
409idempotency_conflictThat Idempotency-Key was already used in the last 24 h with a different request.
409idempotency_in_progressAnother request with the same Idempotency-Key is in progress. Retry in a few seconds.
409client_existsA client with that phone, email or tax id already exists.
409client_erasedThe client requested erasure of their data (GDPR): the record accepts no changes or linked records.
409vehicle_existsThat client already has a vehicle with that plate.
409vehicle_belongs_to_other_clientThat plate is already registered to another client.
409budget_lockedThe budget is closed and no longer accepts this change.
409invalid_status_transitionThe budget cannot move to that status from its current one.
403status_transition_forbiddenThat status change is not available through the API.
403client_acceptance_requiredTo accept a budget use POST /budgets/{id}/accept with the budgets:accept permission and the evidence of who accepts.
403booking_mode_propose_onlyThe workshop works in «propose appointment» mode: only proposals the workshop confirms can be created.
409slot_unavailableThat slot is not available.
413payload_too_largeThe file exceeds the maximum size (4 MB).
415unsupported_media_typeUnsupported file type: only JPEG, PNG, WebP or PDF.
422fiscal_data_incompleteThe customer's tax details are missing, so it cannot be invoiced: check the «missing» list.
409budget_not_invoiceableThe budget cannot be invoiced in its current status.
422invoice_rejectedThe program could not issue the invoice: check the message.
422whatsapp_window_closedMore than 24 h have passed since the customer's last message: on WhatsApp you can only write to them with an approved template (template_id).
409channel_unavailableThat channel is not configured in the shop.
404conversation_not_foundThat conversation does not exist.
404sandbox_onlyOnly available in the test environment (https://demo.programa-taller.es).

Writes and idempotency

Every POST requires the Idempotency-Key header (a fresh UUID per operation). Repeating the same key with the same body within 24 h returns the stored response with Idempotent-Replay: true; with a different body it answers 409 idempotency_conflict. Bodies are validated against their schema and unknown fields are rejected: 422 validation_error with a fields list (path and message).

Guides

Getting started

The same path as the «Get started with the API» tutorial in Developers, for whoever writes the code. Create a test key (pt_test_…) with read-only scopes, check the connection, read real data and, once the integration is ready, switch to a live key with the minimum scopes. Webhooks and writes require the Developer plan or above.

1. Create a key in «My keys»

Pick the test environment and read-only scopes (e.g. budgets:read). The full key is shown only once: store it in a password manager and send it in the Authorization: Bearer header.

2. Check the connection

GET /api/v1/ping

Returns the key name, its scopes and environment. 401 means invalid key; 403, a missing scope.

3. Read your real data

GET /api/v1/budgets

?limit=3

Lists are cursor-paginated: repeat the call with cursor=<next_cursor> until has_more is false. Every response carries X-RateLimit-Remaining with the requests left in the window.

4. Receive webhooks

POST /api/v1/webhooks

{ "url": "https://your-system.com/shop-notices", "events": ["lead.accepted", "vehicle.ready"] }

They can also be created from the Webhooks tab without code. Keep the signing secret and verify X-PT-Signature on every delivery; answer 2xx within 5 seconds.

5. Go live

Before that, you can try writes, acceptances, invoices and messages risk-free in the sandbox (https://demo.programa-taller.es/desarrolladores-sandbox): fictitious data and nothing is really sent. Create a live key with the minimum scopes and, if you write data, add Idempotency-Key to every POST. Limits and the workshop's API plan are shown in the Usage tab; Developer and Business plans can be purchased from within the app.

Guide: create a budget and propose an appointment

Typical flow for a CRM or booking site. Every POST carries an Idempotency-Key (a fresh UUID per operation; reuse it only when retrying the same one). You need a live key with clients:write, vehicles:write, budgets:write, appointments:read and appointments:write.

1. Client: create it or get the existing one

POST /api/v1/clients

{ "name": "Laura Gómez", "phone": "600111222", "email": "laura@ejemplo.com" }

With ?on_conflict=return_existing, if the phone, email or tax id exist you get that client (200) instead of 409.

2. The client's vehicle

POST /api/v1/vehicles

{ "client_id": 1204, "plate": "1234KLM", "brand": "Seat", "model": "León" }

If the plate belongs to another client: 409 vehicle_belongs_to_other_client (the workshop decides).

3. Budget with its lines

POST /api/v1/budgets

{ "client_id": 1204, "vehicle_id": 871, "lines": [{ "description": "Oil and filter change", "quantity": 1, "unit_price": 65 }] }

The response includes the computed totals. The client accepts and signs from the link the workshop sends (the API never returns that link); if they confirm it to you another way, accept on their behalf with POST /budgets/{id}/accept (budgets:accept scope).

4. Free slots

GET /api/v1/appointments/availability

?from=2026-10-14&to=2026-10-18&duration_minutes=60

5. Propose the appointment

POST /api/v1/appointments

{ "budget_id": 1234, "start": "2026-10-14T09:00:00+02:00", "duration_minutes": 60 }

In «propose» mode it stays status=proposed until the workshop confirms it (you get appointment.confirmed by webhook). If the slot was taken: 409 slot_unavailable with alternatives.

Guide: your bot or AI on the workshop's channels

Your assistant answers on WhatsApp, SMS, website chat or email instead of the program's assistant. You need a live key with communications:read, messages:send, settings:write and webhooks:manage (Business or Partner plan). Try it first in the sandbox with POST /sandbox/simulate/message.

1. Subscribe to message.received

POST /api/v1/webhooks

{ "url": "https://your-bot.com/shop", "events": ["message.received"] }

Every client message arrives signed with the conversation key, client, active budget, text and attachments.

2. Turn on the external assistant mode

PUT /api/v1/settings/assistant

{ "external_channels": ["whatsapp", "chat"], "fallback_minutes": 10 }

On those channels the program's assistant stops answering. If you don't reply in time, or your key or webhook stop working, it answers that message again.

3. Read the thread if needed

GET /api/v1/conversations/{key}/messages

4. Reply

POST /api/v1/conversations/{key}/messages

{ "text": "We have a slot tomorrow at 9:00. Shall I book it for you?" }

Outside the WhatsApp 24 h window send template_id (GET /messages/templates). To close the sale: POST /appointments, POST /budgets/{id}/accept or POST /budgets/{id}/invoice depending on your scopes.

Sandbox

https://demo.programa-taller.es is an instance with fictitious data restored every 2 hours. Every key there is a sandbox key with all scopes: it can write, accept, invoice and «send», but nothing is really sent (sends are logged as simulated) and webhooks are emitted anyway to test the full cycle. Your keys, webhooks and request log survive the resets.

1. Get your key

POST /api/v1/sandbox/keys

{ "email": "dev@example.com", "company": "Example Integrations Ltd", "name": "Anna Smith" }

Also from https://demo.programa-taller.es/desarrolladores-sandbox. The key is shown only once and lasts 30 days.

2. Simulate a client writing

POST /api/v1/sandbox/simulate/message

{ "channel": "whatsapp", "from": "+34600111222", "text": "Do you have a slot tomorrow?" }

3. Switch to production

Change the base URL to the workshop's instance and use a live key created in its Developers section.

Scopes

ScopeNameSide effectsDescription
clients:readRead clientsNoView client records and contact details.
clients:writeCreate and edit clientsYesAdd new clients and change existing ones.
vehicles:readRead vehiclesNoView vehicles, plates and their history.
vehicles:writeCreate and edit vehiclesYesAdd vehicles and change their details.
budgets:readRead budgetsNoView budgets, their lines and status.
budgets:writeCreate and edit budgetsYesCreate budgets, add lines and change their status.
budgets:acceptAccept or reject on the customer's behalfYesAccept a budget on the customer's behalf with its evidence (who and through which channel) or reject it with a reason. It is recorded in the history under the key's name.
invoices:readRead invoicesNoRead issued invoices, amounts and payments.
invoices:writeIssue invoices and record paymentsYesIssue the invoice for a budget (the program's numbering, series, Verifactu and accounting) and record payments.
appointments:readRead appointmentsNoView the appointment diary and available slots.
appointments:writeBook and cancel appointmentsYesCreate, move and cancel appointments in the diary.
communications:readRead communicationsNoView the log of emails, SMS, WhatsApp and calls (including full content).
communications:sendSend email and SMSYesSend transactional emails and SMS from the instance; uses credit.
messages:sendReply to conversationsYesReply as the shop in WhatsApp, SMS, web chat and email conversations (external bot or AI); uses credit.
catalog:readRead catalogNoView services, rates and price-list items.
stock:readRead stockNoView parts stock and part numbers.
stock:writeAdjust stockYesRecord parts in and out.
webhooks:manageManage webhooksYesCreate, list and delete this key's event subscriptions.
settings:writeExternal assistant settingsYesRead and change the channels where an external assistant replies instead of the program's assistant.
reports:readRead reportsNoView aggregated revenue, activity and performance figures.

General

GET /api/v1/ping Any key

Test the connection

Returns the key name, environment, scopes and rate-limit state. Any valid key works.

Any valid key, no specific scope.

Example

curl "https://your-shop.example/api/v1/ping" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "ok": true,
  "key": {
    "id": 7,
    "name": "CRM",
    "environment": "live",
    "scopes": [
      "clients:read"
    ],
    "expires_at": null
  },
  "rate_limit": {
    "per_minute": {
      "limit": 60,
      "used": 1,
      "remaining": 59
    },
    "per_day": {
      "limit": 20000,
      "used": 1,
      "remaining": 19999
    }
  },
  "instance": "taller.ejemplo.com",
  "server_time": "2026-10-06T09:30:00.000Z",
  "version": "v1"
}

GET /api/v1/workshop Any key

Workshop public data

Name, legal name, tax id, address, contact details, weekly schedule, appointment booking mode, upcoming holidays and timezone.

Any valid key, no specific scope.

Example

curl "https://your-shop.example/api/v1/workshop" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "name": "Taller Ejemplo",
  "legal_name": "Taller Ejemplo S.L.",
  "tax_id": "B12345678",
  "address": "C/ Industria 4",
  "city": "Barcelona",
  "zip": "08020",
  "province": "Barcelona",
  "phone": "+34931234567",
  "whatsapp": "+34600111222",
  "email": "taller@ejemplo.com",
  "web": "https://www.ejemplo.com",
  "logo_url": null,
  "timezone": "Europe/Madrid",
  "currency": "EUR",
  "booking_mode": "propose",
  "schedule": {
    "mon": {
      "start": "08:00",
      "end": "19:00",
      "closed": false
    },
    "tue": {
      "start": "08:00",
      "end": "19:00",
      "closed": false
    },
    "wed": {
      "start": "08:00",
      "end": "19:00",
      "closed": false
    },
    "thu": {
      "start": "08:00",
      "end": "19:00",
      "closed": false
    },
    "fri": {
      "start": "08:00",
      "end": "19:00",
      "closed": false
    },
    "sat": {
      "start": "08:00",
      "end": "19:00",
      "closed": false
    },
    "sun": {
      "start": "08:00",
      "end": "19:00",
      "closed": false
    }
  },
  "lunch_break": {
    "start": "13:30",
    "end": "15:00"
  },
  "min_slot_minutes": 60,
  "upcoming_holidays": [
    {
      "date": "2026-10-12",
      "name": "Fiesta Nacional de España",
      "scope": "nacional"
    }
  ]
}

GET /api/v1/openapi.json No authentication

OpenAPI 3.1 specification

Generated from this very catalog. No authentication. Accepts ?lang=es|en|ca|pt|fr|bg for the descriptions.

No authentication.

Query

NameTypeRequiredDescription
langstring [es, en, ca, pt, fr, bg] · default esNoLanguage of the descriptions.

Example

curl "https://your-shop.example/api/v1/openapi.json"

Response

{}

Clients

GET /api/v1/clients clients:read

List clients

Ordered by ascending id. Clients erased under GDPR appear anonymised, with erased_at set.

Required scope: clients:read.

Query

NameTypeRequiredDescription
searchstringNoSearches name, phone, email and tax id (2 characters minimum).
expandstring [vehicles]NoOptional relations to include.
limitinteger · default 50NoResults per page (1–200).
cursorstringNoOpaque cursor returned as next_cursor by the previous page.

Example

curl "https://your-shop.example/api/v1/clients" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "data": [
    {
      "id": 1204,
      "name": "Laura Gómez",
      "phone": "+34600111222",
      "phone_secondary": null,
      "whatsapp_phone": null,
      "email": "laura@ejemplo.com",
      "billing_email": null,
      "tax_id": "12345678Z",
      "address": "C/ Mayor 12",
      "city": "Barcelona",
      "zip": "08001",
      "province": "Barcelona",
      "country": "ES",
      "preferred_language": "es",
      "preferred_contact_method": "whatsapp",
      "vip": false,
      "marketing_opt_out": false,
      "channel_opt_out": {
        "email": false,
        "sms": false,
        "whatsapp": false,
        "call": false
      },
      "erased_at": null,
      "vehicles": [
        {
          "id": 871,
          "client_id": 1204,
          "client": null,
          "plate": "1234 KLM",
          "vin": "VSSZZZ5FZJR123456",
          "brand": "Seat",
          "model": "León",
          "variant": "1.5 TSI",
          "year": 2019,
          "registration_date": "2019-03-15",
          "fuel": "Gasolina",
          "transmission": "Manual",
          "engine_code": "DADA",
          "horsepower": 130,
          "displacement": "1498",
          "color_code": null,
          "environmental_label": "C",
          "km": 84500,
          "itv_expiry_date": "2027-03-15",
          "status": "activo"
        }
      ]
    }
  ],
  "next_cursor": "aWQ6MTIzNA",
  "has_more": true
}

POST /api/v1/clients clients:write

Create a client

Never merges into an existing record: if the tax id, email or phone already belong to another client it answers 409 client_exists with existing_id (or 200 with that client when ?on_conflict=return_existing). Phones are stored like in the app (Spain as 9 digits, other countries with prefix), emails lower-cased; typos are not auto-corrected. Marketing opt-outs are recorded in the consent log.

Required scope: clients:write.

Query

NameTypeRequiredDescription
on_conflictstring [error, return_existing] · default errorNoerror (default): 409 when it exists. return_existing: 200 with the existing client.

Headers

NameTypeRequiredDescription
Idempotency-KeystringYesUnique key per operation (UUID recommended). Repeating it with the same body within 24 h returns the stored response with Idempotent-Replay: true; with a different body, 409 idempotency_conflict.

Body

{
  "name": "Laura Gómez",
  "phone": "600111222",
  "phone_secondary": null,
  "email": "laura@ejemplo.com",
  "billing_email": null,
  "tax_id": "12345678Z",
  "address": "C/ Mayor 12",
  "city": "Barcelona",
  "zip": "08001",
  "province": "Barcelona",
  "country": "ES",
  "preferred_language": "es",
  "preferred_contact_method": "whatsapp",
  "marketing_opt_out": false,
  "channel_opt_out": {
    "email": false,
    "sms": false,
    "whatsapp": false,
    "call": false
  }
}

Example

curl -X POST "https://your-shop.example/api/v1/clients" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"Laura Gómez","phone":"600111222","phone_secondary":null,"email":"laura@ejemplo.com","billing_email":null,"tax_id":"12345678Z","address":"C/ Mayor 12","city":"Barcelona","zip":"08001","province":"Barcelona","country":"ES","preferred_language":"es","preferred_contact_method":"whatsapp","marketing_opt_out":false,"channel_opt_out":{"email":false,"sms":false,"whatsapp":false,"call":false}}'

Response

{
  "id": 1204,
  "name": "Laura Gómez",
  "phone": "+34600111222",
  "phone_secondary": null,
  "whatsapp_phone": null,
  "email": "laura@ejemplo.com",
  "billing_email": null,
  "tax_id": "12345678Z",
  "address": "C/ Mayor 12",
  "city": "Barcelona",
  "zip": "08001",
  "province": "Barcelona",
  "country": "ES",
  "preferred_language": "es",
  "preferred_contact_method": "whatsapp",
  "vip": false,
  "marketing_opt_out": false,
  "channel_opt_out": {
    "email": false,
    "sms": false,
    "whatsapp": false,
    "call": false
  },
  "erased_at": null,
  "vehicles": [
    {
      "id": 871,
      "client_id": 1204,
      "client": {
        "id": 1204,
        "name": "Laura Gómez"
      },
      "plate": "1234 KLM",
      "vin": "VSSZZZ5FZJR123456",
      "brand": "Seat",
      "model": "León",
      "variant": "1.5 TSI",
      "year": 2019,
      "registration_date": "2019-03-15",
      "fuel": "Gasolina",
      "transmission": "Manual",
      "engine_code": "DADA",
      "horsepower": 130,
      "displacement": "1498",
      "color_code": null,
      "environmental_label": "C",
      "km": 84500,
      "itv_expiry_date": "2027-03-15",
      "status": "activo"
    }
  ]
}

GET /api/v1/clients/{id} clients:read

Client detail

Required scope: clients:read.

Parameters

NameTypeRequiredDescription
idintegerYesClient id.

Query

NameTypeRequiredDescription
expandstring [vehicles]NoOptional relations to include.

Example

curl "https://your-shop.example/api/v1/clients/1234" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "id": 1204,
  "name": "Laura Gómez",
  "phone": "+34600111222",
  "phone_secondary": null,
  "whatsapp_phone": null,
  "email": "laura@ejemplo.com",
  "billing_email": null,
  "tax_id": "12345678Z",
  "address": "C/ Mayor 12",
  "city": "Barcelona",
  "zip": "08001",
  "province": "Barcelona",
  "country": "ES",
  "preferred_language": "es",
  "preferred_contact_method": "whatsapp",
  "vip": false,
  "marketing_opt_out": false,
  "channel_opt_out": {
    "email": false,
    "sms": false,
    "whatsapp": false,
    "call": false
  },
  "erased_at": null,
  "vehicles": [
    {
      "id": 871,
      "client_id": 1204,
      "client": {
        "id": 1204,
        "name": "Laura Gómez"
      },
      "plate": "1234 KLM",
      "vin": "VSSZZZ5FZJR123456",
      "brand": "Seat",
      "model": "León",
      "variant": "1.5 TSI",
      "year": 2019,
      "registration_date": "2019-03-15",
      "fuel": "Gasolina",
      "transmission": "Manual",
      "engine_code": "DADA",
      "horsepower": 130,
      "displacement": "1498",
      "color_code": null,
      "environmental_label": "C",
      "km": 84500,
      "itv_expiry_date": "2027-03-15",
      "status": "activo"
    }
  ]
}

PATCH /api/v1/clients/{id} clients:write

Update a client

Only the fields sent change (null clears a field). Changing email or phone is allowed and records old → new in the client's activity with the key name; emits client.updated. Setting another client's email, phone or tax id answers 409 client_exists. GDPR-erased clients answer 409 client_erased.

Required scope: clients:write.

Parameters

NameTypeRequiredDescription
idintegerYesClient id.

Headers

NameTypeRequiredDescription
Idempotency-KeystringNoUnique key per operation (UUID recommended). Repeating it with the same body within 24 h returns the stored response with Idempotent-Replay: true; with a different body, 409 idempotency_conflict.

Body

{
  "name": "Laura Gómez Ruiz",
  "phone": "600111222",
  "phone_secondary": null,
  "email": "laura@ejemplo.com",
  "billing_email": null,
  "tax_id": "12345678Z",
  "address": "C/ Mayor 12",
  "city": "Barcelona",
  "zip": "08001",
  "province": "Barcelona",
  "country": "ES",
  "preferred_language": "es",
  "preferred_contact_method": "whatsapp",
  "marketing_opt_out": false,
  "channel_opt_out": {
    "email": false,
    "sms": false,
    "whatsapp": false,
    "call": false
  }
}

Example

curl -X PATCH "https://your-shop.example/api/v1/clients/1234" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"Laura Gómez Ruiz","phone":"600111222","phone_secondary":null,"email":"laura@ejemplo.com","billing_email":null,"tax_id":"12345678Z","address":"C/ Mayor 12","city":"Barcelona","zip":"08001","province":"Barcelona","country":"ES","preferred_language":"es","preferred_contact_method":"whatsapp","marketing_opt_out":false,"channel_opt_out":{"email":false,"sms":false,"whatsapp":false,"call":false}}'

Response

{
  "id": 1204,
  "name": "Laura Gómez",
  "phone": "+34600111222",
  "phone_secondary": null,
  "whatsapp_phone": null,
  "email": "laura@ejemplo.com",
  "billing_email": null,
  "tax_id": "12345678Z",
  "address": "C/ Mayor 12",
  "city": "Barcelona",
  "zip": "08001",
  "province": "Barcelona",
  "country": "ES",
  "preferred_language": "es",
  "preferred_contact_method": "whatsapp",
  "vip": false,
  "marketing_opt_out": false,
  "channel_opt_out": {
    "email": false,
    "sms": false,
    "whatsapp": false,
    "call": false
  },
  "erased_at": null,
  "vehicles": [
    {
      "id": 871,
      "client_id": 1204,
      "client": {
        "id": 1204,
        "name": "Laura Gómez"
      },
      "plate": "1234 KLM",
      "vin": "VSSZZZ5FZJR123456",
      "brand": "Seat",
      "model": "León",
      "variant": "1.5 TSI",
      "year": 2019,
      "registration_date": "2019-03-15",
      "fuel": "Gasolina",
      "transmission": "Manual",
      "engine_code": "DADA",
      "horsepower": 130,
      "displacement": "1498",
      "color_code": null,
      "environmental_label": "C",
      "km": 84500,
      "itv_expiry_date": "2027-03-15",
      "status": "activo"
    }
  ]
}

Vehicles

GET /api/v1/vehicles vehicles:read

List vehicles

Includes the latest recorded mileage and the MOT (ITV) expiry date.

Required scope: vehicles:read.

Query

NameTypeRequiredDescription
platestringNoExact plate (spaces and dashes ignored).
client_idintegerNoFilter by client.
statusstring [activo, baja_temporal, baja]NoVehicle status.
limitinteger · default 50NoResults per page (1–200).
cursorstringNoOpaque cursor returned as next_cursor by the previous page.

Example

curl "https://your-shop.example/api/v1/vehicles" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "data": [
    {
      "id": 871,
      "client_id": 1204,
      "client": {
        "id": 1204,
        "name": "Laura Gómez"
      },
      "plate": "1234 KLM",
      "vin": "VSSZZZ5FZJR123456",
      "brand": "Seat",
      "model": "León",
      "variant": "1.5 TSI",
      "year": 2019,
      "registration_date": "2019-03-15",
      "fuel": "Gasolina",
      "transmission": "Manual",
      "engine_code": "DADA",
      "horsepower": 130,
      "displacement": "1498",
      "color_code": null,
      "environmental_label": "C",
      "km": 84500,
      "itv_expiry_date": "2027-03-15",
      "status": "activo"
    }
  ],
  "next_cursor": "aWQ6MTIzNA",
  "has_more": true
}

POST /api/v1/vehicles vehicles:write

Create a vehicle

Always for an existing client (client_id). The plate is normalised (upper case, no spaces or dashes). If it belongs to ANOTHER client: 409 vehicle_belongs_to_other_client. If the same client already has it: 409 vehicle_exists with existing_id (or 200 with ?on_conflict=return_existing).

Required scope: vehicles:write.

Query

NameTypeRequiredDescription
on_conflictstring [error, return_existing] · default errorNoerror (default) or return_existing.

Headers

NameTypeRequiredDescription
Idempotency-KeystringYesUnique key per operation (UUID recommended). Repeating it with the same body within 24 h returns the stored response with Idempotent-Replay: true; with a different body, 409 idempotency_conflict.

Body

{
  "client_id": 1204,
  "plate": "1234 KLM",
  "vin": "VSSZZZ5FZJR123456",
  "brand": "Seat",
  "model": "León",
  "variant": "1.5 TSI",
  "year": 2019,
  "registration_date": "2019-03-15",
  "fuel": "Gasolina",
  "transmission": "Manual",
  "engine_code": "DADA",
  "horsepower": 130,
  "displacement": "1498",
  "color_code": null,
  "environmental_label": "C",
  "itv_expiry_date": "2027-03-15",
  "status": "activo"
}

Example

curl -X POST "https://your-shop.example/api/v1/vehicles" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"client_id":1204,"plate":"1234 KLM","vin":"VSSZZZ5FZJR123456","brand":"Seat","model":"León","variant":"1.5 TSI","year":2019,"registration_date":"2019-03-15","fuel":"Gasolina","transmission":"Manual","engine_code":"DADA","horsepower":130,"displacement":"1498","color_code":null,"environmental_label":"C","itv_expiry_date":"2027-03-15","status":"activo"}'

Response

{
  "id": 871,
  "client_id": 1204,
  "client": {
    "id": 1204,
    "name": "Laura Gómez"
  },
  "plate": "1234 KLM",
  "vin": "VSSZZZ5FZJR123456",
  "brand": "Seat",
  "model": "León",
  "variant": "1.5 TSI",
  "year": 2019,
  "registration_date": "2019-03-15",
  "fuel": "Gasolina",
  "transmission": "Manual",
  "engine_code": "DADA",
  "horsepower": 130,
  "displacement": "1498",
  "color_code": null,
  "environmental_label": "C",
  "km": 84500,
  "itv_expiry_date": "2027-03-15",
  "status": "activo"
}

GET /api/v1/vehicles/{id} vehicles:read

Vehicle detail

Required scope: vehicles:read.

Parameters

NameTypeRequiredDescription
idintegerYesVehicle id.

Example

curl "https://your-shop.example/api/v1/vehicles/1234" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "id": 871,
  "client_id": 1204,
  "client": {
    "id": 1204,
    "name": "Laura Gómez"
  },
  "plate": "1234 KLM",
  "vin": "VSSZZZ5FZJR123456",
  "brand": "Seat",
  "model": "León",
  "variant": "1.5 TSI",
  "year": 2019,
  "registration_date": "2019-03-15",
  "fuel": "Gasolina",
  "transmission": "Manual",
  "engine_code": "DADA",
  "horsepower": 130,
  "displacement": "1498",
  "color_code": null,
  "environmental_label": "C",
  "km": 84500,
  "itv_expiry_date": "2027-03-15",
  "status": "activo"
}

PATCH /api/v1/vehicles/{id} vehicles:write

Update a vehicle

Partial changes. client_id does not accept null: a vehicle is never unlinked from its owner via the API (it can move to another existing client).

Required scope: vehicles:write.

Parameters

NameTypeRequiredDescription
idintegerYesVehicle id.

Headers

NameTypeRequiredDescription
Idempotency-KeystringNoUnique key per operation (UUID recommended). Repeating it with the same body within 24 h returns the stored response with Idempotent-Replay: true; with a different body, 409 idempotency_conflict.

Body

{
  "client_id": 1204,
  "plate": "1234 KLM",
  "vin": "VSSZZZ5FZJR123456",
  "brand": "Seat",
  "model": "León",
  "variant": "1.5 TSI",
  "year": 2019,
  "registration_date": "2019-03-15",
  "fuel": "Gasolina",
  "transmission": "Manual",
  "engine_code": "DADA",
  "horsepower": 130,
  "displacement": "1498",
  "color_code": null,
  "environmental_label": "C",
  "itv_expiry_date": "2027-03-15",
  "status": "activo"
}

Example

curl -X PATCH "https://your-shop.example/api/v1/vehicles/1234" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"client_id":1204,"plate":"1234 KLM","vin":"VSSZZZ5FZJR123456","brand":"Seat","model":"León","variant":"1.5 TSI","year":2019,"registration_date":"2019-03-15","fuel":"Gasolina","transmission":"Manual","engine_code":"DADA","horsepower":130,"displacement":"1498","color_code":null,"environmental_label":"C","itv_expiry_date":"2027-03-15","status":"activo"}'

Response

{
  "id": 871,
  "client_id": 1204,
  "client": {
    "id": 1204,
    "name": "Laura Gómez"
  },
  "plate": "1234 KLM",
  "vin": "VSSZZZ5FZJR123456",
  "brand": "Seat",
  "model": "León",
  "variant": "1.5 TSI",
  "year": 2019,
  "registration_date": "2019-03-15",
  "fuel": "Gasolina",
  "transmission": "Manual",
  "engine_code": "DADA",
  "horsepower": 130,
  "displacement": "1498",
  "color_code": null,
  "environmental_label": "C",
  "km": 84500,
  "itv_expiry_date": "2027-03-15",
  "status": "activo"
}

GET /api/v1/vehicles/{id}/history vehicles:read

Vehicle history

Workshop visits (all its budgets except internal ones, newest first) with status, check-in and delivery, mileage, amount, invoice number and line concepts; plus interventions recorded at other workshops. Never includes costs.

Required scope: vehicles:read.

Parameters

NameTypeRequiredDescription
idintegerYesVehicle id.

Query

NameTypeRequiredDescription
limitinteger · default 50NoMaximum visits (1–200).

Example

curl "https://your-shop.example/api/v1/vehicles/1234/history" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "vehicle": {
    "id": 871,
    "client_id": 1204,
    "client": {
      "id": 1204,
      "name": "Laura Gómez"
    },
    "plate": "1234 KLM",
    "vin": "VSSZZZ5FZJR123456",
    "brand": "Seat",
    "model": "León",
    "variant": "1.5 TSI",
    "year": 2019,
    "registration_date": "2019-03-15",
    "fuel": "Gasolina",
    "transmission": "Manual",
    "engine_code": "DADA",
    "horsepower": 130,
    "displacement": "1498",
    "color_code": null,
    "environmental_label": "C",
    "km": 84500,
    "itv_expiry_date": "2027-03-15",
    "status": "activo"
  },
  "visits": [
    {
      "budget_id": 1234,
      "status": "Facturado",
      "created_at": "2026-10-06T09:30:00.000Z",
      "checked_in_at": "2026-09-02T07:30:00.000Z",
      "delivered_at": "2026-09-03T16:00:00.000Z",
      "km": 84210,
      "amount": 245.3,
      "invoice": "F26/118",
      "category": "Mantenimiento",
      "works": [
        "Oil and filter change"
      ]
    }
  ],
  "external_interventions": [
    {
      "title": "Tyre change",
      "date": "2025-11-20",
      "km": 78000,
      "workshop_name": null,
      "warranty_until": null
    }
  ]
}

Budgets

GET /api/v1/budgets budgets:read

List budgets

Never includes the workshop's internal budgets nor cost data. Lines and totals are in /budgets/{id}.

Required scope: budgets:read.

Query

NameTypeRequiredDescription
statusstringNoExact status (Pendiente, Enviado, Aprobado, Finalizado, Facturado, Rechazado…).
client_idintegerNoFilter by client.
vehicle_idintegerNoFilter by vehicle.
fromstring (date-time)NoCreated on or after this date.
tostring (date-time)NoCreated on or before this date.
updated_sincestring (date-time)NoOnly records modified on or after this date (ISO 8601).
limitinteger · default 50NoResults per page (1–200).
cursorstringNoOpaque cursor returned as next_cursor by the previous page.

Example

curl "https://your-shop.example/api/v1/budgets" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "data": [
    {
      "id": 1234,
      "status": "Aprobado",
      "created_at": "2026-10-06T09:30:00.000Z",
      "updated_at": "2026-10-06T09:30:00.000Z",
      "channel": "web",
      "client_id": 1204,
      "client": {
        "id": 1204,
        "name": "Laura Gómez"
      },
      "vehicle_id": 871,
      "vehicle": {
        "id": 871,
        "plate": "1234 KLM",
        "brand": "Seat",
        "model": "León"
      },
      "category": {
        "id": 5,
        "name": "Mantenimiento"
      },
      "subcategory": {
        "id": 5,
        "name": "Mantenimiento"
      },
      "assigned_user": {
        "id": 3,
        "name": "Marta"
      },
      "mechanic": {
        "id": 3,
        "name": "Marta"
      },
      "appointment": {
        "start": "2026-10-06T09:30:00.000Z",
        "end": "2026-10-06T10:30:00.000Z",
        "status": "confirmed",
        "client_confirmed_at": null,
        "estimated_duration_minutes": 60,
        "box": null
      },
      "date_in": null,
      "date_out": null,
      "km": 84500,
      "client_reference": null,
      "waiting_parts": false,
      "on_hold": false,
      "hold_until": null,
      "client_signed_at": null,
      "estimated_ready_at": null,
      "delivered_at": null,
      "reject_reason": null
    }
  ],
  "next_cursor": "aWQ6MTIzNA",
  "has_more": true
}

POST /api/v1/budgets budgets:write

Create a budget

Starts as «Pendiente» with channel «API», just like a budget created in the app (log, opening milestone, lead.created webhook). Totals are computed server-side with the workshop's tax; lines without tax_rate use the workshop rate. The vehicle, if given, must belong to the client. Internal-use categories are not allowed. With notify_client=true (and communications:send) the client gets the acknowledgement with their tracking link.

Required scope: budgets:write.

Headers

NameTypeRequiredDescription
Idempotency-KeystringYesUnique key per operation (UUID recommended). Repeating it with the same body within 24 h returns the stored response with Idempotent-Replay: true; with a different body, 409 idempotency_conflict.

Body

{
  "client_id": 1204,
  "vehicle_id": 871,
  "category_id": 5,
  "subcategory_id": 51,
  "client_reference": "PED-2026-118",
  "public_notes": "Also check the suspension noise.",
  "lines": [
    {
      "description": "Oil and filter change",
      "quantity": 1,
      "unit_price": 65,
      "tax_rate": 21,
      "discount_pct": 0,
      "line_type": "labor",
      "reference": null,
      "group_title": null
    }
  ],
  "notify_client": false
}

Example

curl -X POST "https://your-shop.example/api/v1/budgets" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"client_id":1204,"vehicle_id":871,"category_id":5,"subcategory_id":51,"client_reference":"PED-2026-118","public_notes":"Also check the suspension noise.","lines":[{"description":"Oil and filter change","quantity":1,"unit_price":65,"tax_rate":21,"discount_pct":0,"line_type":"labor","reference":null,"group_title":null}],"notify_client":false}'

Response

{
  "id": 1234,
  "status": "Aprobado",
  "created_at": "2026-10-06T09:30:00.000Z",
  "updated_at": "2026-10-06T09:30:00.000Z",
  "channel": "web",
  "client_id": 1204,
  "client": {
    "id": 1204,
    "name": "Laura Gómez"
  },
  "vehicle_id": 871,
  "vehicle": {
    "id": 871,
    "plate": "1234 KLM",
    "brand": "Seat",
    "model": "León"
  },
  "category": {
    "id": 5,
    "name": "Mantenimiento"
  },
  "subcategory": {
    "id": 5,
    "name": "Mantenimiento"
  },
  "assigned_user": {
    "id": 3,
    "name": "Marta"
  },
  "mechanic": {
    "id": 3,
    "name": "Marta"
  },
  "appointment": {
    "start": "2026-10-06T09:30:00.000Z",
    "end": "2026-10-06T10:30:00.000Z",
    "status": "confirmed",
    "client_confirmed_at": null,
    "estimated_duration_minutes": 60,
    "box": {
      "id": 2,
      "name": "Lift 2"
    }
  },
  "date_in": null,
  "date_out": null,
  "km": 84500,
  "client_reference": null,
  "waiting_parts": false,
  "on_hold": false,
  "hold_until": null,
  "client_signed_at": null,
  "estimated_ready_at": null,
  "delivered_at": null,
  "reject_reason": null,
  "public_notes": "Also check the noise in the suspension.",
  "totals": {
    "base": 65,
    "tax": 13.65,
    "total": 78.65,
    "currency": "EUR",
    "tax_rates": [
      {
        "rate": 21,
        "base": 65,
        "quota": 13.65
      }
    ]
  },
  "lines": [
    {
      "id": 5501,
      "description": "Oil and filter change",
      "extended_detail": null,
      "reference": null,
      "line_type": "labor",
      "group_title": null,
      "quantity": 1,
      "unit_price": 65,
      "discount_pct": 0,
      "tax_rate": 21,
      "tax_exempt_code": null,
      "price_estimated": false,
      "base": 65,
      "currency": "EUR",
      "sort_order": 0
    }
  ]
}

GET /api/v1/budgets/{id} budgets:read

Budget detail

Lines (description, quantity, unit price, tax, type, discount), totals with breakdown, appointment, in/out dates, assigned user and public tracking URL.

Required scope: budgets:read.

Parameters

NameTypeRequiredDescription
idintegerYesBudget id.

Example

curl "https://your-shop.example/api/v1/budgets/1234" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "id": 1234,
  "status": "Aprobado",
  "created_at": "2026-10-06T09:30:00.000Z",
  "updated_at": "2026-10-06T09:30:00.000Z",
  "channel": "web",
  "client_id": 1204,
  "client": {
    "id": 1204,
    "name": "Laura Gómez"
  },
  "vehicle_id": 871,
  "vehicle": {
    "id": 871,
    "plate": "1234 KLM",
    "brand": "Seat",
    "model": "León"
  },
  "category": {
    "id": 5,
    "name": "Mantenimiento"
  },
  "subcategory": {
    "id": 5,
    "name": "Mantenimiento"
  },
  "assigned_user": {
    "id": 3,
    "name": "Marta"
  },
  "mechanic": {
    "id": 3,
    "name": "Marta"
  },
  "appointment": {
    "start": "2026-10-06T09:30:00.000Z",
    "end": "2026-10-06T10:30:00.000Z",
    "status": "confirmed",
    "client_confirmed_at": null,
    "estimated_duration_minutes": 60,
    "box": {
      "id": 2,
      "name": "Lift 2"
    }
  },
  "date_in": null,
  "date_out": null,
  "km": 84500,
  "client_reference": null,
  "waiting_parts": false,
  "on_hold": false,
  "hold_until": null,
  "client_signed_at": null,
  "estimated_ready_at": null,
  "delivered_at": null,
  "reject_reason": null,
  "public_notes": "Also check the noise in the suspension.",
  "totals": {
    "base": 65,
    "tax": 13.65,
    "total": 78.65,
    "currency": "EUR",
    "tax_rates": [
      {
        "rate": 21,
        "base": 65,
        "quota": 13.65
      }
    ]
  },
  "lines": [
    {
      "id": 5501,
      "description": "Oil and filter change",
      "extended_detail": null,
      "reference": null,
      "line_type": "labor",
      "group_title": null,
      "quantity": 1,
      "unit_price": 65,
      "discount_pct": 0,
      "tax_rate": 21,
      "tax_exempt_code": null,
      "price_estimated": false,
      "base": 65,
      "currency": "EUR",
      "sort_order": 0
    }
  ]
}

GET /api/v1/budgets/{id}/activity budgets:read

Budget activity

What happened to the budget, newest first: status changes, sends, acceptance (with its origin), appointments, client messages, invoicing… The same log the workshop sees; public=true marks what the client also sees. One-time codes and access links are masked.

Required scope: budgets:read.

Parameters

NameTypeRequiredDescription
idintegerYesBudget id.

Query

NameTypeRequiredDescription
visibilitystring [all, public] · default allNoall: full log; public: only what the client sees.
limitinteger · default 50NoResults per page (1–200).
cursorstringNoOpaque cursor returned as next_cursor by the previous page.

Example

curl "https://your-shop.example/api/v1/budgets/1234/activity" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "data": [
    {
      "id": 88123,
      "at": "2026-10-06T09:30:00.000Z",
      "event": "web_accepted",
      "detail": "Budget accepted by the customer from the tracking page",
      "source": "client",
      "public": true,
      "user": {
        "id": 3,
        "name": "Marta"
      }
    }
  ],
  "next_cursor": "aWQ6MTIzNA",
  "has_more": true
}

POST /api/v1/budgets/{id}/lines budgets:write

Add a line

The other lines keep their ids. Takes a prior snapshot and logs the change like any edit in the app. 409 budget_locked when the budget is invoiced, cancelled, rejected, withdrawn or already has an invoice.

Required scope: budgets:write.

Parameters

NameTypeRequiredDescription
idintegerYesBudget id.

Headers

NameTypeRequiredDescription
Idempotency-KeystringYesUnique key per operation (UUID recommended). Repeating it with the same body within 24 h returns the stored response with Idempotent-Replay: true; with a different body, 409 idempotency_conflict.

Body

{
  "description": "Oil and filter change",
  "quantity": 1,
  "unit_price": 65,
  "tax_rate": 21,
  "discount_pct": 0,
  "line_type": "labor",
  "reference": null,
  "group_title": null
}

Example

curl -X POST "https://your-shop.example/api/v1/budgets/1234/lines" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"description":"Oil and filter change","quantity":1,"unit_price":65,"tax_rate":21,"discount_pct":0,"line_type":"labor","reference":null,"group_title":null}'

Response

{
  "line": {
    "id": 5501,
    "description": "Oil and filter change",
    "extended_detail": null,
    "reference": null,
    "line_type": "labor",
    "group_title": null,
    "quantity": 1,
    "unit_price": 65,
    "discount_pct": 0,
    "tax_rate": 21,
    "tax_exempt_code": null,
    "price_estimated": false,
    "base": 65,
    "currency": "EUR",
    "sort_order": 0
  },
  "budget": {
    "id": 1234,
    "status": "Aprobado",
    "created_at": "2026-10-06T09:30:00.000Z",
    "updated_at": "2026-10-06T09:30:00.000Z",
    "channel": "web",
    "client_id": 1204,
    "client": {
      "id": 1204,
      "name": "Laura Gómez"
    },
    "vehicle_id": 871,
    "vehicle": {
      "id": 871,
      "plate": "1234 KLM",
      "brand": "Seat",
      "model": "León"
    },
    "category": {
      "id": 5,
      "name": "Mantenimiento"
    },
    "subcategory": {
      "id": 5,
      "name": "Mantenimiento"
    },
    "assigned_user": {
      "id": 3,
      "name": "Marta"
    },
    "mechanic": {
      "id": 3,
      "name": "Marta"
    },
    "appointment": {
      "start": "2026-10-06T09:30:00.000Z",
      "end": "2026-10-06T10:30:00.000Z",
      "status": "confirmed",
      "client_confirmed_at": null,
      "estimated_duration_minutes": 60,
      "box": {
        "id": null,
        "name": null
      }
    },
    "date_in": null,
    "date_out": null,
    "km": 84500,
    "client_reference": null,
    "waiting_parts": false,
    "on_hold": false,
    "hold_until": null,
    "client_signed_at": null,
    "estimated_ready_at": null,
    "delivered_at": null,
    "reject_reason": null,
    "public_notes": "Also check the noise in the suspension.",
    "totals": {
      "base": 65,
      "tax": 13.65,
      "total": 78.65,
      "currency": "EUR",
      "tax_rates": [
        {
          "rate": 21,
          "base": 65,
          "quota": 13.65
        }
      ]
    },
    "lines": [
      {
        "id": 5501,
        "description": "Oil and filter change",
        "extended_detail": null,
        "reference": null,
        "line_type": "labor",
        "group_title": null,
        "quantity": 1,
        "unit_price": 65,
        "discount_pct": 0,
        "tax_rate": 21,
        "tax_exempt_code": null,
        "price_estimated": false,
        "base": 65,
        "currency": "EUR",
        "sort_order": 0
      }
    ]
  }
}

PATCH /api/v1/budgets/{id}/lines/{lineId} budgets:write

Update a line

Required scope: budgets:write.

Parameters

NameTypeRequiredDescription
idintegerYesBudget id.
lineIdintegerYesLine id.

Headers

NameTypeRequiredDescription
Idempotency-KeystringNoUnique key per operation (UUID recommended). Repeating it with the same body within 24 h returns the stored response with Idempotent-Replay: true; with a different body, 409 idempotency_conflict.

Body

{
  "description": "Oil and filter change",
  "quantity": 1,
  "unit_price": 65,
  "tax_rate": 21,
  "discount_pct": 0,
  "line_type": "labor",
  "reference": null,
  "group_title": null
}

Example

curl -X PATCH "https://your-shop.example/api/v1/budgets/1234/lines/5501" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"description":"Oil and filter change","quantity":1,"unit_price":65,"tax_rate":21,"discount_pct":0,"line_type":"labor","reference":null,"group_title":null}'

Response

{
  "line": {
    "id": 5501,
    "description": "Oil and filter change",
    "extended_detail": null,
    "reference": null,
    "line_type": "labor",
    "group_title": null,
    "quantity": 1,
    "unit_price": 65,
    "discount_pct": 0,
    "tax_rate": 21,
    "tax_exempt_code": null,
    "price_estimated": false,
    "base": 65,
    "currency": "EUR",
    "sort_order": 0
  },
  "budget": {
    "id": 1234,
    "status": "Aprobado",
    "created_at": "2026-10-06T09:30:00.000Z",
    "updated_at": "2026-10-06T09:30:00.000Z",
    "channel": "web",
    "client_id": 1204,
    "client": {
      "id": 1204,
      "name": "Laura Gómez"
    },
    "vehicle_id": 871,
    "vehicle": {
      "id": 871,
      "plate": "1234 KLM",
      "brand": "Seat",
      "model": "León"
    },
    "category": {
      "id": 5,
      "name": "Mantenimiento"
    },
    "subcategory": {
      "id": 5,
      "name": "Mantenimiento"
    },
    "assigned_user": {
      "id": 3,
      "name": "Marta"
    },
    "mechanic": {
      "id": 3,
      "name": "Marta"
    },
    "appointment": {
      "start": "2026-10-06T09:30:00.000Z",
      "end": "2026-10-06T10:30:00.000Z",
      "status": "confirmed",
      "client_confirmed_at": null,
      "estimated_duration_minutes": 60,
      "box": {
        "id": null,
        "name": null
      }
    },
    "date_in": null,
    "date_out": null,
    "km": 84500,
    "client_reference": null,
    "waiting_parts": false,
    "on_hold": false,
    "hold_until": null,
    "client_signed_at": null,
    "estimated_ready_at": null,
    "delivered_at": null,
    "reject_reason": null,
    "public_notes": "Also check the noise in the suspension.",
    "totals": {
      "base": 65,
      "tax": 13.65,
      "total": 78.65,
      "currency": "EUR",
      "tax_rates": [
        {
          "rate": 21,
          "base": 65,
          "quota": 13.65
        }
      ]
    },
    "lines": [
      {
        "id": 5501,
        "description": "Oil and filter change",
        "extended_detail": null,
        "reference": null,
        "line_type": "labor",
        "group_title": null,
        "quantity": 1,
        "unit_price": 65,
        "discount_pct": 0,
        "tax_rate": 21,
        "tax_exempt_code": null,
        "price_estimated": false,
        "base": 65,
        "currency": "EUR",
        "sort_order": 0
      }
    ]
  }
}

DELETE /api/v1/budgets/{id}/lines/{lineId} budgets:write

Delete a line

Returns the budget with recalculated totals. The line remains in the prior snapshot of the version history.

Required scope: budgets:write.

Parameters

NameTypeRequiredDescription
idintegerYesBudget id.
lineIdintegerYesLine id.

Example

curl -X DELETE "https://your-shop.example/api/v1/budgets/1234/lines/5501" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "id": 1234,
  "status": "Aprobado",
  "created_at": "2026-10-06T09:30:00.000Z",
  "updated_at": "2026-10-06T09:30:00.000Z",
  "channel": "web",
  "client_id": 1204,
  "client": {
    "id": 1204,
    "name": "Laura Gómez"
  },
  "vehicle_id": 871,
  "vehicle": {
    "id": 871,
    "plate": "1234 KLM",
    "brand": "Seat",
    "model": "León"
  },
  "category": {
    "id": 5,
    "name": "Mantenimiento"
  },
  "subcategory": {
    "id": 5,
    "name": "Mantenimiento"
  },
  "assigned_user": {
    "id": 3,
    "name": "Marta"
  },
  "mechanic": {
    "id": 3,
    "name": "Marta"
  },
  "appointment": {
    "start": "2026-10-06T09:30:00.000Z",
    "end": "2026-10-06T10:30:00.000Z",
    "status": "confirmed",
    "client_confirmed_at": null,
    "estimated_duration_minutes": 60,
    "box": {
      "id": 2,
      "name": "Lift 2"
    }
  },
  "date_in": null,
  "date_out": null,
  "km": 84500,
  "client_reference": null,
  "waiting_parts": false,
  "on_hold": false,
  "hold_until": null,
  "client_signed_at": null,
  "estimated_ready_at": null,
  "delivered_at": null,
  "reject_reason": null,
  "public_notes": "Also check the noise in the suspension.",
  "totals": {
    "base": 65,
    "tax": 13.65,
    "total": 78.65,
    "currency": "EUR",
    "tax_rates": [
      {
        "rate": 21,
        "base": 65,
        "quota": 13.65
      }
    ]
  },
  "lines": [
    {
      "id": 5501,
      "description": "Oil and filter change",
      "extended_detail": null,
      "reference": null,
      "line_type": "labor",
      "group_title": null,
      "quantity": 1,
      "unit_price": 65,
      "discount_pct": 0,
      "tax_rate": 21,
      "tax_exempt_code": null,
      "price_estimated": false,
      "base": 65,
      "currency": "EUR",
      "sort_order": 0
    }
  ]
}

POST /api/v1/budgets/{id}/status budgets:write

Change the status

Accepts Pendiente/En cotización/Enviado (before acceptance), En curso (already accepted), Finalizado (from Aprobado, En curso or En espera) and Cancelado. «Aprobado» answers 403 client_acceptance_required: acceptance is signed by the client from the link the workshop sends, or recorded on their behalf by your integration with POST /budgets/{id}/accept (budgets:accept scope). Rejecting goes through POST /budgets/{id}/reject and invoicing through POST /budgets/{id}/invoice (invoices:write scope); here they answer 403 status_transition_forbidden, like withdrawing; from Facturado or Cancelado, 409 budget_locked. «Enviado» also requires communications:send and sent_via: it records that YOUR system already sent it (it does not send). No change notifies the client except Finalizado with notify_client=true and communications:send.

Required scope: budgets:write.

Parameters

NameTypeRequiredDescription
idintegerYesBudget id.

Headers

NameTypeRequiredDescription
Idempotency-KeystringYesUnique key per operation (UUID recommended). Repeating it with the same body within 24 h returns the stored response with Idempotent-Replay: true; with a different body, 409 idempotency_conflict.

Body

{
  "status": "En curso",
  "sent_via": "email",
  "notify_client": false
}

Example

curl -X POST "https://your-shop.example/api/v1/budgets/1234/status" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"status":"En curso","sent_via":"email","notify_client":false}'

Response

{
  "id": 1234,
  "status": "Aprobado",
  "created_at": "2026-10-06T09:30:00.000Z",
  "updated_at": "2026-10-06T09:30:00.000Z",
  "channel": "web",
  "client_id": 1204,
  "client": {
    "id": 1204,
    "name": "Laura Gómez"
  },
  "vehicle_id": 871,
  "vehicle": {
    "id": 871,
    "plate": "1234 KLM",
    "brand": "Seat",
    "model": "León"
  },
  "category": {
    "id": 5,
    "name": "Mantenimiento"
  },
  "subcategory": {
    "id": 5,
    "name": "Mantenimiento"
  },
  "assigned_user": {
    "id": 3,
    "name": "Marta"
  },
  "mechanic": {
    "id": 3,
    "name": "Marta"
  },
  "appointment": {
    "start": "2026-10-06T09:30:00.000Z",
    "end": "2026-10-06T10:30:00.000Z",
    "status": "confirmed",
    "client_confirmed_at": null,
    "estimated_duration_minutes": 60,
    "box": {
      "id": 2,
      "name": "Lift 2"
    }
  },
  "date_in": null,
  "date_out": null,
  "km": 84500,
  "client_reference": null,
  "waiting_parts": false,
  "on_hold": false,
  "hold_until": null,
  "client_signed_at": null,
  "estimated_ready_at": null,
  "delivered_at": null,
  "reject_reason": null,
  "public_notes": "Also check the noise in the suspension.",
  "totals": {
    "base": 65,
    "tax": 13.65,
    "total": 78.65,
    "currency": "EUR",
    "tax_rates": [
      {
        "rate": 21,
        "base": 65,
        "quota": 13.65
      }
    ]
  },
  "lines": [
    {
      "id": 5501,
      "description": "Oil and filter change",
      "extended_detail": null,
      "reference": null,
      "line_type": "labor",
      "group_title": null,
      "quantity": 1,
      "unit_price": 65,
      "discount_pct": 0,
      "tax_rate": 21,
      "tax_exempt_code": null,
      "price_estimated": false,
      "base": 65,
      "currency": "EUR",
      "sort_order": 0
    }
  ]
}

POST /api/v1/budgets/{id}/accept budgets:accept

Accept on behalf of the client

For when the client accepts through another channel (phone, in person, your website…). Evidence is mandatory: accepted_by and channel (phone, in_person, email, whatsapp, other); note is optional. Goes through the program's single acceptance rule: Aprobado status, transition, minimum client tax data (if missing, 422 fiscal_data_incomplete with missing), campaign discount, internal notice to the workshop, confirmation to the client per the configured notices and lead.accepted and budget.accepted webhooks. Only from «Enviado» (already accepted answers 200 with already=true); Cancelado, Rechazado, Desistido, Finalizado or Facturado answer 409 budget_locked. If the workshop requires a signature, the API accepts anyway and records it: «sin firma, aceptado por integración» (signature=waived_by_integration). The log reads «Aceptado por API en nombre del cliente · integración <key> · <accepted_by> por <channel>».

Required scope: budgets:accept.

Parameters

NameTypeRequiredDescription
idintegerYesBudget id.

Headers

NameTypeRequiredDescription
Idempotency-KeystringYesUnique key per operation (UUID recommended). Repeating it with the same body within 24 h returns the stored response with Idempotent-Replay: true; with a different body, 409 idempotency_conflict.

Body

{
  "accepted_by": "Laura Gómez",
  "channel": "phone",
  "note": "Confirmed by phone at 10:12"
}

Example

curl -X POST "https://your-shop.example/api/v1/budgets/1234/accept" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"accepted_by":"Laura Gómez","channel":"phone","note":"Confirmed by phone at 10:12"}'

Response

{
  "budget": {
    "id": 1234,
    "status": "Aprobado",
    "created_at": "2026-10-06T09:30:00.000Z",
    "updated_at": "2026-10-06T09:30:00.000Z",
    "channel": "web",
    "client_id": 1204,
    "client": {
      "id": 1204,
      "name": "Laura Gómez"
    },
    "vehicle_id": 871,
    "vehicle": {
      "id": 871,
      "plate": "1234 KLM",
      "brand": "Seat",
      "model": "León"
    },
    "category": {
      "id": 5,
      "name": "Mantenimiento"
    },
    "subcategory": {
      "id": 5,
      "name": "Mantenimiento"
    },
    "assigned_user": {
      "id": 3,
      "name": "Marta"
    },
    "mechanic": {
      "id": 3,
      "name": "Marta"
    },
    "appointment": {
      "start": "2026-10-06T09:30:00.000Z",
      "end": "2026-10-06T10:30:00.000Z",
      "status": "confirmed",
      "client_confirmed_at": null,
      "estimated_duration_minutes": 60,
      "box": null
    },
    "date_in": null,
    "date_out": null,
    "km": 84500,
    "client_reference": null,
    "waiting_parts": false,
    "on_hold": false,
    "hold_until": null,
    "client_signed_at": null,
    "estimated_ready_at": null,
    "delivered_at": null,
    "reject_reason": null,
    "public_notes": "Also check the noise in the suspension.",
    "totals": {
      "base": 65,
      "tax": 13.65,
      "total": 78.65,
      "currency": "EUR",
      "tax_rates": [
        {
          "rate": 21,
          "base": 65,
          "quota": 13.65
        }
      ]
    },
    "lines": [
      {
        "id": 5501,
        "description": "Oil and filter change",
        "extended_detail": null,
        "reference": null,
        "line_type": "labor",
        "group_title": null,
        "quantity": 1,
        "unit_price": 65,
        "discount_pct": 0,
        "tax_rate": 21,
        "tax_exempt_code": null,
        "price_estimated": false,
        "base": 65,
        "currency": "EUR",
        "sort_order": 0
      }
    ]
  },
  "already": false,
  "signature": "not_required"
}

POST /api/v1/budgets/{id}/reject budgets:accept

Reject on behalf of the client

Reason required. Same rule as a client rejection: from Pendiente, En cotización, Enviado or Aprobado (if the vehicle has not checked in). Emits lead.rejected and budget.rejected and is logged with the key name.

Required scope: budgets:accept.

Parameters

NameTypeRequiredDescription
idintegerYesBudget id.

Headers

NameTypeRequiredDescription
Idempotency-KeystringYesUnique key per operation (UUID recommended). Repeating it with the same body within 24 h returns the stored response with Idempotent-Replay: true; with a different body, 409 idempotency_conflict.

Body

{
  "reason": "They will do it at another shop",
  "rejected_by": "Laura Gómez",
  "channel": "phone"
}

Example

curl -X POST "https://your-shop.example/api/v1/budgets/1234/reject" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"reason":"They will do it at another shop","rejected_by":"Laura Gómez","channel":"phone"}'

Response

{
  "budget": {
    "id": 1234,
    "status": "Aprobado",
    "created_at": "2026-10-06T09:30:00.000Z",
    "updated_at": "2026-10-06T09:30:00.000Z",
    "channel": "web",
    "client_id": 1204,
    "client": {
      "id": 1204,
      "name": "Laura Gómez"
    },
    "vehicle_id": 871,
    "vehicle": {
      "id": 871,
      "plate": "1234 KLM",
      "brand": "Seat",
      "model": "León"
    },
    "category": {
      "id": 5,
      "name": "Mantenimiento"
    },
    "subcategory": {
      "id": 5,
      "name": "Mantenimiento"
    },
    "assigned_user": {
      "id": 3,
      "name": "Marta"
    },
    "mechanic": {
      "id": 3,
      "name": "Marta"
    },
    "appointment": {
      "start": "2026-10-06T09:30:00.000Z",
      "end": "2026-10-06T10:30:00.000Z",
      "status": "confirmed",
      "client_confirmed_at": null,
      "estimated_duration_minutes": 60,
      "box": null
    },
    "date_in": null,
    "date_out": null,
    "km": 84500,
    "client_reference": null,
    "waiting_parts": false,
    "on_hold": false,
    "hold_until": null,
    "client_signed_at": null,
    "estimated_ready_at": null,
    "delivered_at": null,
    "reject_reason": null,
    "public_notes": "Also check the noise in the suspension.",
    "totals": {
      "base": 65,
      "tax": 13.65,
      "total": 78.65,
      "currency": "EUR",
      "tax_rates": [
        {
          "rate": 21,
          "base": 65,
          "quota": 13.65
        }
      ]
    },
    "lines": [
      {
        "id": 5501,
        "description": "Oil and filter change",
        "extended_detail": null,
        "reference": null,
        "line_type": "labor",
        "group_title": null,
        "quantity": 1,
        "unit_price": 65,
        "discount_pct": 0,
        "tax_rate": 21,
        "tax_exempt_code": null,
        "price_estimated": false,
        "base": 65,
        "currency": "EUR",
        "sort_order": 0
      }
    ]
  },
  "already": false,
  "signature": "not_required"
}

POST /api/v1/budgets/{id}/documents budgets:write

Attach a document

multipart/form-data with the «file» field (JPEG, PNG, WebP or PDF, checked by content; 4 MB max). Staff-only by default; client_visible=true shows it on the tracking page and mechanic_visible=true in the mechanic app. The idempotency fingerprint includes the file.

Required scope: budgets:write.

Parameters

NameTypeRequiredDescription
idintegerYesBudget id.

Headers

NameTypeRequiredDescription
Idempotency-KeystringYesUnique key per operation (UUID recommended). Repeating it with the same body within 24 h returns the stored response with Idempotent-Replay: true; with a different body, 409 idempotency_conflict.

Body (multipart/form-data)

NameTypeRequiredDescription
filestring (binary)YesFichero
client_visiblestring [true, false]No
mechanic_visiblestring [true, false]No

Example

curl -X POST "https://your-shop.example/api/v1/budgets/1234/documents" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "file=@fichero.pdf" \
  -F "client_visible=false" \
  -F "mechanic_visible=false"

Response

{
  "id": 991,
  "budget_id": 1234,
  "filename": "parte-de-trabajo.pdf",
  "content_type": "application/pdf",
  "size": 182044,
  "url": "https://…/leads/1234/api-parte-de-trabajo.pdf",
  "client_visible": false,
  "mechanic_visible": false,
  "created_at": "2026-10-06T09:30:00.000Z"
}

Invoices

POST /api/v1/budgets/{id}/invoice invoices:write

Invoice a budget

Uses the program's own invoicing: copies the budget lines and tax, creates the accounting entry and, with issue=true (default), issues the invoice with the right series, sequential number, chained hash and Verifactu QR. The budget becomes Facturado. Budgets in Aprobado, En curso, En espera or Finalizado with an amount can be invoiced; if it already has an invoice that one is returned (created=false), never a second one. Emits invoice.created and invoice.issued. Corrective invoices are not available through the API: they are made in the program.

Required scope: invoices:write.

Parameters

NameTypeRequiredDescription
idintegerYesBudget id.

Headers

NameTypeRequiredDescription
Idempotency-KeystringYesUnique key per operation (UUID recommended). Repeating it with the same body within 24 h returns the stored response with Idempotent-Replay: true; with a different body, 409 idempotency_conflict.

Body

{
  "issue": true,
  "pay_method": "TARJETA"
}

Example

curl -X POST "https://your-shop.example/api/v1/budgets/1234/invoice" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"issue":true,"pay_method":"TARJETA"}'

Response

{
  "invoice": {
    "id": 412,
    "number": 87,
    "series": "F26",
    "full_number": "F2687",
    "kind": "invoice",
    "rectifies_number": null,
    "status": "issued",
    "date": "2026-10-06",
    "issued_at": "2026-10-06T09:30:00.000Z",
    "client_id": 1204,
    "client": {
      "id": 1204,
      "name": "Laura Gómez"
    },
    "budget_id": 1234,
    "vehicle_id": 871,
    "vehicle": {
      "id": 871,
      "plate": "1234 KLM",
      "brand": "Seat",
      "model": "León"
    },
    "plate": "1234 KLM",
    "km": 84500,
    "total": 78.65,
    "currency": "EUR",
    "payments": {
      "paid": 78.65,
      "pending": 0,
      "settled": true
    },
    "payment_method": "Tarjeta",
    "rebu": false,
    "verifactu_hash": "3f9a…",
    "registered_externally": false,
    "billing": {
      "name": "Laura Gómez",
      "tax_id": "12345678Z",
      "address": "C/ Mayor 12",
      "city": "Barcelona",
      "zip": "08001",
      "province": "Barcelona"
    },
    "date_in": null,
    "date_out": null,
    "public_notes": null,
    "totals": {
      "base": 65,
      "tax": 13.65,
      "total": 78.65,
      "currency": "EUR",
      "tax_rates": [
        {
          "rate": 21,
          "base": 65,
          "quota": 13.65
        }
      ]
    },
    "lines": [
      {
        "id": 9001,
        "description": "Oil and filter change",
        "reference": null,
        "group_title": null,
        "quantity": 1,
        "unit_price": 65,
        "discount_pct": 0,
        "tax_rate": 21,
        "tax_exempt_code": null,
        "base": 65,
        "currency": "EUR",
        "sort_order": 0
      }
    ],
    "payment_list": [
      {
        "id": 77,
        "date": "2026-10-06T09:30:00.000Z",
        "amount": 78.65,
        "currency": "EUR",
        "method": "Tarjeta"
      }
    ]
  },
  "created": true
}

GET /api/v1/invoices invoices:read

List invoices

Issued invoices and drafts ordered by id, with a payments summary.

Required scope: invoices:read.

Query

NameTypeRequiredDescription
fromstring (date-time)NoInvoice date from.
tostring (date-time)NoInvoice date to.
client_idintegerNoFilter by client.
statusstring [draft, issued, cancelled]NoInvoice status.
seriesstringNoExact series.
limitinteger · default 50NoResults per page (1–200).
cursorstringNoOpaque cursor returned as next_cursor by the previous page.

Example

curl "https://your-shop.example/api/v1/invoices" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "data": [
    {
      "id": 412,
      "number": 87,
      "series": "F26",
      "full_number": "F2687",
      "kind": "invoice",
      "rectifies_number": null,
      "status": "issued",
      "date": "2026-10-06",
      "issued_at": "2026-10-06T09:30:00.000Z",
      "client_id": 1204,
      "client": {
        "id": 1204,
        "name": "Laura Gómez"
      },
      "budget_id": 1234,
      "vehicle_id": 871,
      "vehicle": {
        "id": 871,
        "plate": "1234 KLM",
        "brand": "Seat",
        "model": "León"
      },
      "plate": "1234 KLM",
      "km": 84500,
      "total": 78.65,
      "currency": "EUR",
      "payments": {
        "paid": 78.65,
        "pending": 0,
        "settled": true
      },
      "payment_method": "Tarjeta",
      "rebu": false,
      "verifactu_hash": "3f9a…",
      "registered_externally": false
    }
  ],
  "next_cursor": "aWQ6MTIzNA",
  "has_more": true
}

GET /api/v1/invoices/{id} invoices:read

Invoice detail

Required scope: invoices:read.

Parameters

NameTypeRequiredDescription
idintegerYesInvoice id.

Example

curl "https://your-shop.example/api/v1/invoices/1234" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "id": 412,
  "number": 87,
  "series": "F26",
  "full_number": "F2687",
  "kind": "invoice",
  "rectifies_number": null,
  "status": "issued",
  "date": "2026-10-06",
  "issued_at": "2026-10-06T09:30:00.000Z",
  "client_id": 1204,
  "client": {
    "id": 1204,
    "name": "Laura Gómez"
  },
  "budget_id": 1234,
  "vehicle_id": 871,
  "vehicle": {
    "id": 871,
    "plate": "1234 KLM",
    "brand": "Seat",
    "model": "León"
  },
  "plate": "1234 KLM",
  "km": 84500,
  "total": 78.65,
  "currency": "EUR",
  "payments": {
    "paid": 78.65,
    "pending": 0,
    "settled": true
  },
  "payment_method": "Tarjeta",
  "rebu": false,
  "verifactu_hash": "3f9a…",
  "registered_externally": false,
  "billing": {
    "name": "Laura Gómez",
    "tax_id": "12345678Z",
    "address": "C/ Mayor 12",
    "city": "Barcelona",
    "zip": "08001",
    "province": "Barcelona"
  },
  "date_in": null,
  "date_out": null,
  "public_notes": null,
  "totals": {
    "base": 65,
    "tax": 13.65,
    "total": 78.65,
    "currency": "EUR",
    "tax_rates": [
      {
        "rate": 21,
        "base": 65,
        "quota": 13.65
      }
    ]
  },
  "lines": [
    {
      "id": 9001,
      "description": "Oil and filter change",
      "reference": null,
      "group_title": null,
      "quantity": 1,
      "unit_price": 65,
      "discount_pct": 0,
      "tax_rate": 21,
      "tax_exempt_code": null,
      "base": 65,
      "currency": "EUR",
      "sort_order": 0
    }
  ],
  "payment_list": [
    {
      "id": 77,
      "date": "2026-10-06T09:30:00.000Z",
      "amount": 78.65,
      "currency": "EUR",
      "method": "Tarjeta"
    }
  ]
}

GET /api/v1/invoices/{id}/pdf invoices:read

Invoice PDF

The same PDF the program generates (with the Verifactu QR when issued). application/pdf response.

Required scope: invoices:read.

Parameters

NameTypeRequiredDescription
idintegerYesInvoice id.

Example

curl "https://your-shop.example/api/v1/invoices/1234/pdf" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

(application/pdf)

POST /api/v1/invoices/{id}/payments invoices:write

Record a payment

Same payment log as the invoice screen: the «paid» flag is recalculated from all payments (never forced) and payment.received is emitted. Issued invoices only. Returns the invoice with its payments summary.

Required scope: invoices:write.

Parameters

NameTypeRequiredDescription
idintegerYesInvoice id.

Headers

NameTypeRequiredDescription
Idempotency-KeystringYesUnique key per operation (UUID recommended). Repeating it with the same body within 24 h returns the stored response with Idempotent-Replay: true; with a different body, 409 idempotency_conflict.

Body

{
  "amount": 245.3,
  "date": "2026-10-13",
  "pay_method": "TARJETA",
  "notes": "Paid at the counter"
}

Example

curl -X POST "https://your-shop.example/api/v1/invoices/1234/payments" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"amount":245.3,"date":"2026-10-13","pay_method":"TARJETA","notes":"Paid at the counter"}'

Response

{
  "id": 412,
  "number": 87,
  "series": "F26",
  "full_number": "F2687",
  "kind": "invoice",
  "rectifies_number": null,
  "status": "issued",
  "date": "2026-10-06",
  "issued_at": "2026-10-06T09:30:00.000Z",
  "client_id": 1204,
  "client": {
    "id": 1204,
    "name": "Laura Gómez"
  },
  "budget_id": 1234,
  "vehicle_id": 871,
  "vehicle": {
    "id": 871,
    "plate": "1234 KLM",
    "brand": "Seat",
    "model": "León"
  },
  "plate": "1234 KLM",
  "km": 84500,
  "total": 78.65,
  "currency": "EUR",
  "payments": {
    "paid": 78.65,
    "pending": 0,
    "settled": true
  },
  "payment_method": "Tarjeta",
  "rebu": false,
  "verifactu_hash": "3f9a…",
  "registered_externally": false,
  "billing": {
    "name": "Laura Gómez",
    "tax_id": "12345678Z",
    "address": "C/ Mayor 12",
    "city": "Barcelona",
    "zip": "08001",
    "province": "Barcelona"
  },
  "date_in": null,
  "date_out": null,
  "public_notes": null,
  "totals": {
    "base": 65,
    "tax": 13.65,
    "total": 78.65,
    "currency": "EUR",
    "tax_rates": [
      {
        "rate": 21,
        "base": 65,
        "quota": 13.65
      }
    ]
  },
  "lines": [
    {
      "id": 9001,
      "description": "Oil and filter change",
      "reference": null,
      "group_title": null,
      "quantity": 1,
      "unit_price": 65,
      "discount_pct": 0,
      "tax_rate": 21,
      "tax_exempt_code": null,
      "base": 65,
      "currency": "EUR",
      "sort_order": 0
    }
  ],
  "payment_list": [
    {
      "id": 77,
      "date": "2026-10-06T09:30:00.000Z",
      "amount": 78.65,
      "currency": "EUR",
      "method": "Tarjeta"
    }
  ]
}

Appointments

GET /api/v1/appointments appointments:read

Confirmed and proposed appointments

Defaults to the next 30 days. status=confirmed are booked appointments; status=proposed are client proposals awaiting workshop confirmation (they block the slot).

Required scope: appointments:read.

Query

NameTypeRequiredDescription
fromstring (date-time)NoRange start (defaults to now).
tostring (date-time)NoRange end (defaults to +30 days, 1 year max).
statusstring [confirmed, proposed]NoOnly one kind.
box_idintegerNoFilter by bay/box.

Example

curl "https://your-shop.example/api/v1/appointments" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "data": [
    {
      "id": "b1234",
      "budget_id": 1234,
      "status": "confirmed",
      "start": "2026-10-06T09:30:00.000Z",
      "end": "2026-10-06T10:30:00.000Z",
      "estimated_duration_minutes": 60,
      "client_confirmed_at": null,
      "budget_status": "Aprobado",
      "checked_in_at": null,
      "client": {
        "id": 1204,
        "name": "Laura Gómez"
      },
      "vehicle": {
        "id": 871,
        "plate": "1234 KLM",
        "brand": "Seat",
        "model": "León"
      },
      "mechanic": {
        "id": 3,
        "name": "Marta"
      },
      "box": {
        "id": 2,
        "name": "Lift 2"
      },
      "category": {
        "id": 5,
        "name": "Mantenimiento"
      },
      "channel": null,
      "proposed_at": null
    }
  ],
  "from": "2026-10-06T00:00:00.000Z",
  "to": "2026-11-05T00:00:00.000Z"
}

POST /api/v1/appointments appointments:write

Propose or book an appointment

Follows the workshop booking mode (booking_mode in GET /workshop). In «propose» a proposal is created (status=proposed) that blocks the slot until the workshop confirms it; asking mode=book answers 403 booking_mode_propose_only. In «book» the appointment is confirmed (status=confirmed) unless you ask mode=propose. The slot is checked with the same logic as /appointments/availability; if not free, 409 slot_unavailable with up to 3 alternatives in error.alternatives. The client is not notified unless notify_client=true with communications:send.

Required scope: appointments:write.

Headers

NameTypeRequiredDescription
Idempotency-KeystringYesUnique key per operation (UUID recommended). Repeating it with the same body within 24 h returns the stored response with Idempotent-Replay: true; with a different body, 409 idempotency_conflict.

Body

{
  "budget_id": 1234,
  "start": "2026-10-14T09:00:00+02:00",
  "box_id": 2,
  "duration_minutes": 60,
  "mode": "propose",
  "notify_client": false
}

Example

curl -X POST "https://your-shop.example/api/v1/appointments" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"budget_id":1234,"start":"2026-10-14T09:00:00+02:00","box_id":2,"duration_minutes":60,"mode":"propose","notify_client":false}'

Response

{
  "id": "b1234",
  "budget_id": 1234,
  "status": "confirmed",
  "start": "2026-10-06T09:30:00.000Z",
  "end": "2026-10-06T10:30:00.000Z",
  "estimated_duration_minutes": 60,
  "client_confirmed_at": null,
  "budget_status": "Aprobado",
  "checked_in_at": null,
  "client": {
    "id": 1204,
    "name": "Laura Gómez"
  },
  "vehicle": {
    "id": 871,
    "plate": "1234 KLM",
    "brand": "Seat",
    "model": "León"
  },
  "mechanic": {
    "id": 3,
    "name": "Marta"
  },
  "box": {
    "id": 2,
    "name": "Lift 2"
  },
  "category": {
    "id": 5,
    "name": "Mantenimiento"
  },
  "channel": null,
  "proposed_at": null
}

GET /api/v1/appointments/availability appointments:read

Free slots

Same logic as the agenda and the tracking page: workshop and bay hours, lunch break, national/regional/local holidays, open appointments and pending proposals (which block their slot). Starts every 30 min, at least 1 h from now. Defaults to the next 7 days (31 max). Includes the workshop booking_mode.

Required scope: appointments:read.

Query

NameTypeRequiredDescription
fromstring (date-time)NoFrom (defaults to now).
tostring (date-time)NoTo (defaults to +7 days; 31 days max).
duration_minutesintegerNoAppointment length (15–720). Defaults to the agenda minimum.
box_idintegerNoOnly that bay.
limitinteger · default 100NoMaximum slots (1–500).

Example

curl "https://your-shop.example/api/v1/appointments/availability" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "data": [
    {
      "start": "2026-10-14T07:00:00.000Z",
      "end": "2026-10-14T08:00:00.000Z",
      "box": {
        "id": 2,
        "name": "Lift 2"
      }
    }
  ],
  "duration_minutes": 60,
  "from": "2026-10-14T00:00:00.000Z",
  "to": "2026-10-21T00:00:00.000Z",
  "booking_mode": "propose"
}

DELETE /api/v1/appointments/{id} appointments:write

Cancel an appointment or withdraw a proposal

b<budget>: cancels the confirmed appointment (same as «Cancel appointment» in the app). p<proposal>: withdraws the pending proposal; with notify_client=true and communications:send the client is invited to pick another time. Emits appointment.cancelled.

Required scope: appointments:write.

Parameters

NameTypeRequiredDescription
idstringYesAppointment id (b1234 or p88).

Query

NameTypeRequiredDescription
notify_clientboolean · default falseNoProposals only: notify the client.

Example

curl -X DELETE "https://your-shop.example/api/v1/appointments/b1234" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "ok": true,
  "id": "b1234",
  "status": "cancelled"
}

GET /api/v1/appointments/{id} appointments:read

Appointment detail

Required scope: appointments:read.

Parameters

NameTypeRequiredDescription
idstringYesAppointment id (b1234 or p88).

Example

curl "https://your-shop.example/api/v1/appointments/b1234" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "id": "b1234",
  "budget_id": 1234,
  "status": "confirmed",
  "start": "2026-10-06T09:30:00.000Z",
  "end": "2026-10-06T10:30:00.000Z",
  "estimated_duration_minutes": 60,
  "client_confirmed_at": null,
  "budget_status": "Aprobado",
  "checked_in_at": null,
  "client": {
    "id": 1204,
    "name": "Laura Gómez"
  },
  "vehicle": {
    "id": 871,
    "plate": "1234 KLM",
    "brand": "Seat",
    "model": "León"
  },
  "mechanic": {
    "id": 3,
    "name": "Marta"
  },
  "box": {
    "id": 2,
    "name": "Lift 2"
  },
  "category": {
    "id": 5,
    "name": "Mantenimiento"
  },
  "channel": null,
  "proposed_at": null
}

PATCH /api/v1/appointments/{id} appointments:write

Move an appointment or change a proposal

b<budget>: moves the confirmed appointment to the new time (only if the workshop works in «book» mode; in «propose» mode it answers 403 booking_mode_propose_only: create a proposal with POST /appointments). p<proposal>: withdraws the proposal and creates a new one at the new time (the id changes). The slot is checked like on creation (409 slot_unavailable with alternatives). Emits appointment.updated.

Required scope: appointments:write.

Parameters

NameTypeRequiredDescription
idstringYesAppointment id (b1234 or p88).

Headers

NameTypeRequiredDescription
Idempotency-KeystringNoUnique key per operation (UUID recommended). Repeating it with the same body within 24 h returns the stored response with Idempotent-Replay: true; with a different body, 409 idempotency_conflict.

Body

{
  "start": "2026-10-15T10:00:00+02:00",
  "box_id": 2,
  "duration_minutes": 60,
  "notify_client": false
}

Example

curl -X PATCH "https://your-shop.example/api/v1/appointments/b1234" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"start":"2026-10-15T10:00:00+02:00","box_id":2,"duration_minutes":60,"notify_client":false}'

Response

{
  "id": "b1234",
  "budget_id": 1234,
  "status": "confirmed",
  "start": "2026-10-06T09:30:00.000Z",
  "end": "2026-10-06T10:30:00.000Z",
  "estimated_duration_minutes": 60,
  "client_confirmed_at": null,
  "budget_status": "Aprobado",
  "checked_in_at": null,
  "client": {
    "id": 1204,
    "name": "Laura Gómez"
  },
  "vehicle": {
    "id": 871,
    "plate": "1234 KLM",
    "brand": "Seat",
    "model": "León"
  },
  "mechanic": {
    "id": 3,
    "name": "Marta"
  },
  "box": {
    "id": 2,
    "name": "Lift 2"
  },
  "category": {
    "id": 5,
    "name": "Mantenimiento"
  },
  "channel": null,
  "proposed_at": null
}

Catalog

GET /api/v1/catalog/services catalog:read

Service categories and subcategories

Required scope: catalog:read.

Example

curl "https://your-shop.example/api/v1/catalog/services" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "data": [
    {
      "id": 5,
      "name": "Mantenimiento",
      "reference_price": 120,
      "currency": "EUR",
      "subcategories": [
        {
          "id": 51,
          "name": "Oil change",
          "reference_price": 65,
          "currency": "EUR"
        }
      ]
    }
  ]
}

GET /api/v1/catalog/rates catalog:read

Labor rates

Sale price per hour only; cost never leaves through the API.

Required scope: catalog:read.

Example

curl "https://your-shop.example/api/v1/catalog/rates" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "data": [
    {
      "id": 1,
      "name": "General labour",
      "price_per_hour": 48,
      "currency": "EUR",
      "is_default": true
    }
  ]
}

Parts stock

GET /api/v1/stock stock:read

List stock parts

Quantities, references and sale price. Purchase cost, supplier and purchase history never leave through the API. Active parts only by default.

Required scope: stock:read.

Query

NameTypeRequiredDescription
searchstringNoSearches name, brand, references and EAN (references ignoring spaces, dots and dashes).
referencestringNoExact reference or EAN, ignoring spaces, dots and dashes.
in_stockbooleanNotrue: only with units; false: only out of stock.
include_inactiveboolean · default falseNoInclude parts removed from inventory.
updated_sincestring (date-time)NoOnly records modified on or after this date (ISO 8601).
limitinteger · default 50NoResults per page (1–200).
cursorstringNoOpaque cursor returned as next_cursor by the previous page.

Example

curl "https://your-shop.example/api/v1/stock" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "data": [
    {
      "id": 88,
      "name": "Turbocompresor",
      "brand": "Garrett",
      "references": {
        "original": "A6540907801",
        "supplier": "MA654 090 78 01",
        "own": null
      },
      "ean": null,
      "quantity": 1,
      "location": "Shelf B3",
      "status": "nuevo",
      "sale_price": 2190,
      "currency": "EUR",
      "active": true,
      "updated_at": "2026-10-06T09:30:00.000Z"
    }
  ],
  "next_cursor": "aWQ6MTIzNA",
  "has_more": true
}

GET /api/v1/stock/{id} stock:read

Stock part detail

Required scope: stock:read.

Parameters

NameTypeRequiredDescription
idintegerYesPart id.

Example

curl "https://your-shop.example/api/v1/stock/1234" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "id": 88,
  "name": "Turbocompresor",
  "brand": "Garrett",
  "references": {
    "original": "A6540907801",
    "supplier": "MA654 090 78 01",
    "own": null
  },
  "ean": null,
  "quantity": 1,
  "location": "Shelf B3",
  "status": "nuevo",
  "sale_price": 2190,
  "currency": "EUR",
  "active": true,
  "updated_at": "2026-10-06T09:30:00.000Z"
}

Communications

GET /api/v1/communications communications:read

Communications log

Latest communications (email, SMS, WhatsApp, calls, push) with full content, newest first.

Required scope: communications:read.

Query

NameTypeRequiredDescription
channelstring [all, email, sms, whatsapp, call, push] · default allNoChannel.
limitinteger · default 50NoMaximum results (1–200).

Example

curl "https://your-shop.example/api/v1/communications" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "data": [
    {
      "id": "c_8812",
      "channel": "email",
      "direction": "out",
      "recipient": "laura@ejemplo.com",
      "subject": "Your budget",
      "body": "Hi Laura, …",
      "idlead": 1234,
      "idclient": 1204,
      "clientName": "Laura Gómez",
      "status": "sent",
      "created_at": "2026-10-06T09:30:00.000Z",
      "duration": null,
      "recordingUrl": null,
      "agent": null,
      "fromNumber": null,
      "toNumber": null
    }
  ],
  "next_cursor": null,
  "has_more": false
}

GET /api/v1/logs communications:read

Communications log (legacy alias)

Same query as /communications but returns { items }. Kept for compatibility; prefer /communications.

Required scope: communications:read.

Query

NameTypeRequiredDescription
channelstring [all, email, sms, whatsapp, call, push] · default allNoChannel.
limitinteger · default 50NoMaximum results (1–200).

Example

curl "https://your-shop.example/api/v1/logs" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "items": [
    {
      "id": "c_8812",
      "channel": "email",
      "direction": "out",
      "recipient": "laura@ejemplo.com",
      "subject": "Your budget",
      "body": "Hi Laura, …",
      "idlead": 1234,
      "idclient": 1204,
      "clientName": "Laura Gómez",
      "status": "sent",
      "created_at": "2026-10-06T09:30:00.000Z",
      "duration": null,
      "recordingUrl": null,
      "agent": null,
      "fromNumber": null,
      "toNumber": null
    }
  ]
}

POST /api/v1/email communications:send

Send a transactional email

Plain text only: sent with the workshop's template, name and email account, and logged in Communications. HTML and custom senders are not accepted, and replyTo must be an address on the workshop's domain. If it bounces, the client's email is flagged as invalid.

Required scope: communications:send.

Body

{
  "to": "cliente@ejemplo.com",
  "subject": "Your vehicle is ready",
  "text": "You can come and collect it.",
  "replyTo": "taller@ejemplo.com"
}

Example

curl -X POST "https://your-shop.example/api/v1/email" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"to":"cliente@ejemplo.com","subject":"Your vehicle is ready","text":"You can come and collect it.","replyTo":"taller@ejemplo.com"}'

Response

{
  "ok": true
}

POST /api/v1/sms communications:send

Send a transactional SMS

Sent with the SMS service configured by the workshop and logged in Communications, where its delivery status is updated.

Required scope: communications:send.

Body

{
  "to": "+34600111222",
  "body": "Your vehicle is ready for collection."
}

Example

curl -X POST "https://your-shop.example/api/v1/sms" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"to":"+34600111222","body":"Your vehicle is ready for collection."}'

Response

{
  "ok": true
}

Conversations

GET /api/v1/conversations communications:read

Inbox conversations

WhatsApp, SMS, website chat and email in one list, like the program's Inbox, newest first. Each with its stable key (channel:number or channel:id), client, active budget, status (open: needs a reply; pending: waiting for the client; closed) and whether the WhatsApp 24 h window is still open.

Required scope: communications:read.

Query

NameTypeRequiredDescription
channelstring [whatsapp, sms, chat, email]NoOnly one channel.
statusstring [open, pending, closed]NoOnly one status.
daysinteger · default 30NoActivity in the last N days (1–365).
limitinteger · default 50NoMaximum results (1–200).

Example

curl "https://your-shop.example/api/v1/conversations" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "data": [
    {
      "key": "whatsapp:600111222",
      "channel": "whatsapp",
      "contact": "+34600111222",
      "client": {
        "id": 1204,
        "name": "Laura Gómez"
      },
      "budget_id": 1234,
      "status": "open",
      "unread": 1,
      "last_message_at": "2026-10-06T09:30:00.000Z",
      "last_inbound_at": "2026-10-06T09:29:00.000Z",
      "last_message": "What time can I come to pick up the car?",
      "last_author": "cliente",
      "whatsapp_window_open": true,
      "external_bot": false
    }
  ]
}

GET /api/v1/conversations/{key}/messages communications:read

Conversation messages

The full thread in chronological order, with author (cliente, ia, equipo, automatico or integracion), text and attachments. Emails are returned as text, without the template or the quoted thread.

Required scope: communications:read.

Parameters

NameTypeRequiredDescription
keystringYesConversation key: whatsapp:<9 digits>, sms:<9 digits>, chat:<id> or email:<id>.

Example

curl "https://your-shop.example/api/v1/conversations/whatsapp:600111222/messages" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "conversation": {
    "key": "whatsapp:600111222",
    "channel": "whatsapp",
    "contact": "+34600111222",
    "client": {
      "id": 1204,
      "name": "Laura Gómez"
    },
    "budget_id": 1234,
    "status": "open",
    "unread": 1,
    "last_message_at": "2026-10-06T09:30:00.000Z",
    "last_inbound_at": "2026-10-06T09:29:00.000Z",
    "last_message": "What time can I come to pick up the car?",
    "last_author": "cliente",
    "whatsapp_window_open": true,
    "external_bot": false
  },
  "data": [
    {
      "id": 77120,
      "at": "2026-10-06T09:30:00.000Z",
      "direction": "in",
      "author": "cliente",
      "author_name": null,
      "subject": null,
      "text": "What time can I come to pick up the car?",
      "attachments": [
        "https://…/whatsapp-in/SM123-0.jpg"
      ],
      "status": "received"
    }
  ]
}

POST /api/v1/conversations/{key}/messages messages:send

Reply in a conversation

Goes out through the same channel and functions as the program's Inbox. WhatsApp: text and/or media_url within the 24 h window; outside it only with template_id (approved template; otherwise 422 whatsapp_window_closed). SMS: text (one segment). Website chat: text. Email: subject and text. The message is logged with the integration as author («API · <key>»), marks the conversation as answered and, if a message was waiting for the external assistant, cancels the program assistant's fallback reply. In the sandbox nothing is really sent (simulated=true).

Required scope: messages:send.

Parameters

NameTypeRequiredDescription
keystringYesConversation key: whatsapp:<9 digits>, sms:<9 digits>, chat:<id> or email:<id>.

Headers

NameTypeRequiredDescription
Idempotency-KeystringYesUnique key per operation (UUID recommended). Repeating it with the same body within 24 h returns the stored response with Idempotent-Replay: true; with a different body, 409 idempotency_conflict.

Body

{
  "text": "Your car will be ready at 6:00 pm.",
  "media_url": null,
  "template_id": 12,
  "template_variables": {
    "#nombre#": "Laura"
  },
  "subject": "Your budget"
}

Example

curl -X POST "https://your-shop.example/api/v1/conversations/whatsapp:600111222/messages" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"text":"Your car will be ready at 6:00 pm.","media_url":null,"template_id":12,"template_variables":{"#nombre#":"Laura"},"subject":"Your budget"}'

Response

{
  "ok": true,
  "key": "whatsapp:600111222",
  "channel": "whatsapp",
  "mode": "free",
  "simulated": false
}

GET /api/v1/messages/templates communications:read

Approved WhatsApp templates

The templates Meta approved for the workshop: their id is the template_id to write outside the 24 h window.

Required scope: communications:read.

Example

curl "https://your-shop.example/api/v1/messages/templates" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "data": [
    {
      "id": 12,
      "name": "presupuesto_listo",
      "language": "es",
      "category": "UTILITY",
      "body": "Hello #nombre#, your budget is ready.",
      "variables": [
        "#nombre#"
      ]
    }
  ]
}

Settings

GET /api/v1/settings/assistant settings:write

External assistant mode

Which channels your assistant answers instead of the program's assistant, the key that handles them, the fallback minutes and the channels you really own right now (live key and active message.received webhook).

Required scope: settings:write.

Example

curl "https://your-shop.example/api/v1/settings/assistant" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "external_channels": [
    "whatsapp"
  ],
  "api_key_id": 7,
  "fallback_minutes": 10,
  "channels_owned_now": [
    "whatsapp"
  ]
}

PUT /api/v1/settings/assistant settings:write

Change the external assistant mode

On the external_channels the program's assistant stops answering: each message comes in, is logged, message.received is emitted and your reply is awaited (POST /conversations/{key}/messages). Safeguard: if you don't reply within fallback_minutes (10 by default), if the key is revoked or expires, or if there is no active message.received webhook or its delivery fails, the program's assistant answers that message and it is logged. The calling key becomes the handling key. external_channels=[] gives everything back to the program.

Required scope: settings:write.

Headers

NameTypeRequiredDescription
Idempotency-KeystringNoUnique key per operation (UUID recommended). Repeating it with the same body within 24 h returns the stored response with Idempotent-Replay: true; with a different body, 409 idempotency_conflict.

Body

{
  "external_channels": [
    "whatsapp"
  ],
  "fallback_minutes": 10
}

Example

curl -X PUT "https://your-shop.example/api/v1/settings/assistant" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"external_channels":["whatsapp"],"fallback_minutes":10}'

Response

{
  "external_channels": [
    "whatsapp"
  ],
  "api_key_id": 7,
  "fallback_minutes": 10,
  "channels_owned_now": [
    "whatsapp"
  ]
}

Sandbox

POST /api/v1/sandbox/keys No authentication

Request a sandbox key

Only on https://demo.programa-taller.es (other instances answer 404 sandbox_only). No authentication or cost: returns a pt_test_… key with every scope, valid for 30 days, shown only once. Up to 3 per day per IP and per email. Demo data is fictitious and is restored every 2 hours; keys, webhooks and the request log are kept. Nothing is really sent: sends are logged as simulated and webhooks are emitted anyway.

No authentication.

Headers

NameTypeRequiredDescription
Idempotency-KeystringNoUnique key per operation (UUID recommended). Repeating it with the same body within 24 h returns the stored response with Idempotent-Replay: true; with a different body, 409 idempotency_conflict.

Body

{
  "email": "dev@ejemplo.com",
  "company": "Example Integrations Ltd",
  "name": "Anna Smith"
}

Example

curl -X POST "https://your-shop.example/api/v1/sandbox/keys" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"email":"dev@ejemplo.com","company":"Example Integrations Ltd","name":"Anna Smith"}'

Response

{
  "key": "pt_test_0123456789abcdef0123456789abcdef",
  "expires_at": "2026-11-12T10:00:00.000Z",
  "base_url": "https://demo.programa-taller.es/api/v1",
  "docs_url": "https://demo.programa-taller.es/api/v1/openapi.json",
  "scopes": [
    "budgets:accept"
  ]
}

POST /api/v1/sandbox/simulate/message Any key

Simulate an inbound message

Sandbox only. Creates a fictitious inbound message by WhatsApp, SMS, website chat or email, as if a client had written it: it enters the Inbox, is linked to the client if the phone or email match and fires message.received so you can test your bot end to end. Reply with POST /conversations/{key}/messages (the reply is simulated).

Any valid key, no specific scope.

Headers

NameTypeRequiredDescription
Idempotency-KeystringYesUnique key per operation (UUID recommended). Repeating it with the same body within 24 h returns the stored response with Idempotent-Replay: true; with a different body, 409 idempotency_conflict.

Body

{
  "channel": "whatsapp",
  "from": "+34600111222",
  "text": "Hello, do you have a slot tomorrow for an oil change?",
  "subject": "Consulta",
  "media_urls": []
}

Example

curl -X POST "https://your-shop.example/api/v1/sandbox/simulate/message" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"channel":"whatsapp","from":"+34600111222","text":"Hello, do you have a slot tomorrow for an oil change?","subject":"Consulta","media_urls":[]}'

Response

{
  "ok": true,
  "key": "whatsapp:600111222"
}

Webhooks

GET /api/v1/webhooks webhooks:manage

List this key's webhooks

Includes the catalog of available events. Never returns secrets.

Required scope: webhooks:manage.

Example

curl "https://your-shop.example/api/v1/webhooks" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "items": [
    {
      "id": 3,
      "url": "https://tu-sistema.com/webhooks/taller",
      "events": [
        "lead.accepted"
      ],
      "description": "CRM",
      "active": true,
      "created_at": "2026-10-06T09:30:00.000Z"
    }
  ],
  "events": [
    {
      "event": "lead.accepted",
      "label": "Budget accepted",
      "description": "texto"
    }
  ]
}

POST /api/v1/webhooks webhooks:manage

Create a webhook

The signing secret (whsec_…) is only returned in this response.

Required scope: webhooks:manage.

Body

{
  "url": "https://tu-sistema.com/webhooks/taller",
  "events": [
    "lead.accepted"
  ],
  "description": "CRM"
}

Example

curl -X POST "https://your-shop.example/api/v1/webhooks" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://tu-sistema.com/webhooks/taller","events":["lead.accepted"],"description":"CRM"}'

Response

{
  "item": {
    "id": 3,
    "url": "https://tu-sistema.com/webhooks/taller",
    "events": [
      "lead.accepted"
    ],
    "description": "CRM",
    "active": true,
    "created_at": "2026-10-06T09:30:00.000Z"
  },
  "secret": "whsec_…"
}

GET /api/v1/webhooks/{id} webhooks:manage

Webhook detail and recent deliveries

Required scope: webhooks:manage.

Parameters

NameTypeRequiredDescription
idintegerYesWebhook id.

Example

curl "https://your-shop.example/api/v1/webhooks/1234" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "item": {
    "id": 3,
    "url": "https://tu-sistema.com/webhooks/taller",
    "events": [
      "lead.accepted"
    ],
    "description": "CRM",
    "active": true,
    "created_at": "2026-10-06T09:30:00.000Z"
  },
  "deliveries": [
    {}
  ]
}

PATCH /api/v1/webhooks/{id} webhooks:manage

Update a webhook

Required scope: webhooks:manage.

Parameters

NameTypeRequiredDescription
idintegerYesWebhook id.

Body

{
  "url": "texto",
  "events": [
    "texto"
  ],
  "description": "texto",
  "active": false
}

Example

curl -X PATCH "https://your-shop.example/api/v1/webhooks/1234" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"texto","events":["texto"],"description":"texto","active":false}'

Response

{
  "item": {
    "id": 3,
    "url": "https://tu-sistema.com/webhooks/taller",
    "events": [
      "lead.accepted"
    ],
    "description": "CRM",
    "active": true,
    "created_at": "2026-10-06T09:30:00.000Z"
  }
}

DELETE /api/v1/webhooks/{id} webhooks:manage

Delete a webhook

Required scope: webhooks:manage.

Parameters

NameTypeRequiredDescription
idintegerYesWebhook id.

Example

curl -X DELETE "https://your-shop.example/api/v1/webhooks/1234" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "ok": true
}

POST /api/v1/webhooks/{id}/test webhooks:manage

Send a test delivery (test.ping) to the webhook

Required scope: webhooks:manage.

Parameters

NameTypeRequiredDescription
idintegerYesWebhook id.

Example

curl -X POST "https://your-shop.example/api/v1/webhooks/1234/test" \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "ok": true,
  "status": 200
}

Webhooks

Payload

{
  "event": "lead.accepted",
  "timestamp": "2026-10-06T10:15:00.000Z",
  "data": {
    "leadId": 1234,
    "from": "Enviado",
    "to": "Aprobado"
  }
}
EventDescription
lead.createdBudget created
A new budget was created (from the app, the website, email or the assistant).
lead.sentBudget sent
The budget was sent to the client.
lead.acceptedBudget accepted
The client or the workshop approved the budget.
lead.rejectedBudget rejected
The budget was rejected, with the reason if there is one.
lead.status_changedStatus change
Any budget status change (includes the ones above).
budget.acceptedBudget accepted (budget)
Same as lead.accepted, under the new name: the budget has moved to Approved (customer, shop or integration with budgets:accept).
budget.rejectedBudget rejected (budget)
Same as lead.rejected, under the new name: the budget has moved to Rejected, with its reason.
appointment.proposedAppointment proposed
A client proposes an appointment the workshop still has to confirm.
appointment.confirmedAppointment confirmed
An appointment is confirmed in the diary.
appointment.cancelledAppointment cancelled
A budget's appointment was cancelled.
appointment.createdAppointment created
A budget that had no appointment is now booked in the schedule (program, tracking page, assistant or API).
appointment.updatedAppointment changed
The date, time or bay of an existing appointment has been moved, or a proposal has been changed through the API.
vehicle.createdVehicle created
A vehicle has been registered.
vehicle.updatedVehicle updated
The data or status of a vehicle has been modified.
vehicle.checked_inVehicle checked in
The vehicle entered the workshop (check-in or walk-in).
vehicle.arrivingCustomer on the way
The customer reports from their check-in link that they are on the way, will be late or are already at the shop, with the estimated time.
vehicle.readyVehicle ready
The repair is finished and the vehicle is ready for collection.
vehicle.arrivedCustomer at reception
Staff mark in the reception queue that the customer has arrived at the counter (kiosk or mobile check-in emits vehicle.checked_in).
vehicle.eta_updatedEstimated delivery time
The estimated delivery time of the vehicle has been set or changed; it indicates whether the customer was told.
vehicle.deliveredVehicle delivered
The client collected the vehicle.
vehicle.pickup_plannedPickup scheduled
The customer has chosen the day and time slot to pick up the vehicle (date, slot: morning/afternoon/any).
courtesy_car.loanedCourtesy car lent
A courtesy car has been handed to the customer with a signed contract (plate, departure mileage and fuel, expected return).
courtesy_car.returnedCourtesy car returned
The customer has returned the courtesy car (return mileage and fuel, extra days and km calculated).
invoice.createdInvoice created
An invoice has been created (still a draft, without a final number), for example when invoicing a budget.
invoice.issuedInvoice issued
An invoice was issued with its final number.
payment.receivedPayment recorded
A payment was recorded against an invoice.
client.createdClient created
A client was created.
client.updatedClient updated
A client's details were changed.
communication.inboundInbound message
An email, SMS, WhatsApp or call arrived from a client.
message.receivedMessage received in a conversation
A customer has written via WhatsApp, SMS, web chat or email: conversation (stable key channel:number), customer, active budget, text, attachments and date, and whether the external assistant should reply (external_bot).
call.completedCall analysed
A call (from the team or the voice assistant) has ended and been analysed: summary, reason, sentiment and transcript if available.
email.sentEmail sent
An email was sent (campaigns, notices or API).
email.failedEmail failed
An email could not be sent.
email.openedEmail opened
The recipient opened the email.
email.clickedEmail click
The recipient clicked a link in the email.
email.unsubscribedEmail unsubscribe
The recipient unsubscribed from emails.
email.bouncedEmail bounced
The email bounced.
sms.sentSMS sent
An SMS was sent.
sms.failedSMS failed
An SMS could not be sent.
sms.unsubscribedSMS opt-out
The recipient asked not to receive SMS.
whatsapp.unsubscribedWhatsApp opt-out
The recipient asked not to receive WhatsApp messages.
campaign.finishedCampaign finished
A campaign finished sending.
3 months for €1