generated: '2026-08-08'
method: derived
source: openapi/_original/buk-data-access-api-chile-openapi.json + https://demo.buk.cl/apidocs +
  https://supportcenter.buk.cl/hc/es-419/articles/46268700701723--C%C3%B3mo-funciona-nuestra-API
authentication:
  style: API key in a custom header
  header: auth_token
  issuance: Generated by a tenant administrator inside the Buk platform under Configuración > Acceso
    API > Crear nueva API Key
  scoping: Tokens are scoped per entity with two permission levels — Lectura, and Lectura y Modificación.
    Every operation description in the contract names the entity permission it requires.
  notes: The Swagger 2.0 contracts declare securityDefinitions.auth_token but do NOT apply a global
    or per-operation security block, so a generated client will not attach the header automatically.
    Buk Asistencia uses a different header name (token); the biometric ingestion endpoint uses a
    header pair (x-provider-name + x-provider-token).
  artifact: authentication/buk-authentication.yml
multi_tenancy:
  style: Subdomain per customer
  pattern: https://{tenant}.buk.cl/api/v1/{country}
  countries:
  - chile
  - colombia
  - peru
  - mexico
  - brasil
  note: The country segment is part of the path, not a header, and each country is a separate contract.
    The tenant subdomain is echoed back to integrators in every webhook payload as tenant_url.
pagination:
  style: page-number
  request_params:
  - page
  - page_size
  default_page_size: 25
  max_page_size: 100
  max_page_size_scope: Documented on Buk Asistencia; the Data Access API documents page/page_size
    per operation without stating a ceiling.
  response_fields:
  - pagination.next
  - pagination.previous
  - pagination.count
  - pagination.page
  - pagination.totalPages
  operations_with_pagination: 69
idempotency:
  supported: false
  evidence: No Idempotency-Key (or any idempotency) header, parameter, or documented behaviour appears
    in any of the seven harvested Buk contracts, in the apidocs page, or in the support-center integration
    articles. Retrying a POST creates a duplicate record.
  closest_signal: A 409 "Records are being updated concurrently" response exists on the bulk employee
    update path — optimistic concurrency, not idempotency.
sorting:
  param: sort
  note: Only the value "id" is accepted on /employees; default ordering is by name.
filtering:
  style: flat query parameters per operation; no shared filter grammar
  common:
  - status
  - company_id
  - employee_id
  - from
  - to
  - start_date
  - end_date
  - year
  - month
  - code
  - email
field_expansion:
  supported: false
  note: No expand/include/fields parameter is declared anywhere in the contract.
request_id_tracing:
  supported: false
  note: No request-id / correlation-id header is documented.
content_types:
  consumes:
  - application/json
  produces:
  - application/json
  - application/pdf
versioning:
  style: URL path major version
  current: v1
  introspection: GET /versions returns the versions the tenant is running
  artifact: lifecycle/buk-lifecycle.yml
errors:
  artifact: errors/buk-problem-types.yml
  envelope: plain JSON; not RFC 9457
rate_limiting:
  documented: false
  evidence: No 429 response appears in any of 206 Data Access operations or the 11 Asistencia/biometric
    operations, and no rate-limit headers are documented. The support center states only that there
    is no defined limit on the number of API tokens an administrator may create — which is a token
    quota, not a request rate limit.
events:
  artifact: asyncapi/buk-webhooks.yml
  note: 'Webhooks are notification-only: the payload carries an id, a timestamp, an event_type and
    the tenant_url, and the integrator must call the API to read the changed record.'