DePix App Meta API

openapi: 3.2.0
info:
  title: Depixapp Com Meta API
  version: 0.50.0
  contact:
    name: DePix
    url: https://depixapp.com
  description: 'Operations tagged meta across 2 of this provider''s published API definitions: depixapp-com-openapi.json, depixapp-com-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.depixapp.com
  description: Canonical API base URL
- url: https://depix-backend.vercel.app
  description: legacy alias
security:
- apiKey: []
tags:
- name: Meta
  description: Service metadata.
paths:
  /api/health:
    get:
      tags:
      - Meta
      operationId: getHealth
      summary: Health check
      description: 'Dependency health. Contract: HTTP 200 = healthy, HTTP 503 = degraded (branch on the status code).'
      security: []
      responses:
        '200':
          description: Healthy.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
              examples:
                ok:
                  value:
                    status: ok
                    turso: true
                    redis: true
                    schema: true
                    timestamp: '2026-07-01T12:00:00.000Z'
        '503':
          description: Degraded — the body says which dependency failed.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
              examples:
                degraded:
                  value:
                    status: degraded
                    turso: true
                    redis: false
                    schema: true
                    timestamp: '2026-07-01T12:00:00.000Z'
    servers:
    - url: https://api.depixapp.com
      description: Canonical API base URL
    - url: https://depix-backend.vercel.app
      description: legacy alias
  /openapi.json:
    get:
      tags:
      - Meta
      operationId: getOpenapiDocument
      summary: This OpenAPI document
      description: 'Serves this OpenAPI 3.1 document (Cache-Control: public, max-age=300).'
      security: []
      responses:
        '200':
          description: The OpenAPI 3.1 document.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                description: This OpenAPI 3.1 document.
              examples:
                document:
                  summary: Truncated illustration
                  value:
                    openapi: 3.1.0
                    info:
                      title: DePix API
                      version: 0.1.0
        '429':
          description: Rate limited (per-IP, per-key or per-merchant window). Retry after `retry_after` seconds (also in the Retry-After header).
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
              examples:
                rate_limited:
                  value:
                    response:
                      errorMessage: Muitas requisições. Tente novamente em 1 minuto.
                    error:
                      code: rate_limited
                      message: Too many requests for this scope.
                      request_id: gru1::iad1::v9x4k-1751476800000-abc123
                      retry_after: 37
                      docs_url: https://depixapp.com/docs/en/#errors
                      details:
                        scope: deposit
    servers:
    - url: https://api.depixapp.com
      description: Canonical API base URL
    - url: https://depix-backend.vercel.app
      description: legacy alias
components:
  headers:
    XRequestId:
      description: Request correlation id — present on EVERY response (success and error). Matches error.request_id in error bodies.
      schema:
        type: string
    RetryAfter:
      description: Seconds to wait before retrying (mirrors error.retry_after).
      schema:
        type: integer
  schemas:
    ErrorEnvelope:
      type: object
      description: Dual error envelope. `response.errorMessage` is the legacy human-readable Portuguese contract; `error` is the additive machine-readable contract for agents (English). Some legacy sibling fields survive for backwards compatibility (`response.errors`, top-level `blocked`).
      required:
      - response
      - error
      additionalProperties: false
      properties:
        response:
          type: object
          description: Legacy envelope — Portuguese message, first in the body (SPA/integrator contract).
          required:
          - errorMessage
          additionalProperties: false
          properties:
            errorMessage:
              type: string
              description: Human-readable error message in Portuguese (legacy contract).
            errors:
              type: array
              description: Per-field validation errors — legacy sibling emitted by POST /api/checkouts on validation_error.
              items:
                type: object
                description: One field-level validation failure.
                required:
                - field
                - message
                additionalProperties: false
                properties:
                  field:
                    type: string
                    description: Name of the offending request field.
                  message:
                    type: string
                    description: Portuguese validation message for the field.
        blocked:
          type: boolean
          description: Legacy sibling present only on 403 `account_blocked` responses (always true when present).
        error:
          type: object
          description: Machine-readable error object (agent contract, English messages).
          required:
          - code
          - message
          - request_id
          - docs_url
          additionalProperties: false
          properties:
            code:
              type: string
              description: Stable machine-readable error code. The enum below is the complete closed catalog — branch on this value, never on messages.
              enum:
              - unauthorized
              - invalid_api_key
              - invalid_token
              - agent_invalid_signature
              - agent_signature_expired
              - agent_replay_detected
              - agent_unknown_key
              - invalid_operator_token
              - invalid_password
              - insufficient_scope
              - oauth_account_not_linked
              - account_already_linked
              - workos_identity_in_use
              - account_blocked
              - account_suspended
              - operator_token_revoked
              - agent_account_no_password
              - registration_blocked
              - domain_required
              - graduation_pending
              - merchant_required
              - verification_required
              - step_up_required
              - live_access_required
              - whatsapp_verification_required
              - withdraw_disabled
              - external_wallet_disabled
              - first_withdraw_tax_number_mismatch
              - sandbox_only
              - validation_error
              - password_required
              - tax_number_required
              - amount_out_of_range
              - account_limit_exceeded
              - key_limit_exceeded
              - provider_refused
              - attachment_too_large
              - not_found
              - conflict
              - charge_already_paid
              - depix_not_enabled
              - depix_busy
              - depix_address_unsupported
              - depix_address_conflict
              - invalid_blinding_key
              - discount_changed
              - charge_payment_in_progress
              - charge_payment_pending
              - agent_pubkey_exists
              - email_in_use
              - account_exists
              - ticket_closed
              - ticket_open
              - already_rated
              - verification_requirements_not_met
              - verification_tax_number_in_use
              - verification_unavailable
              - username_taken
              - idempotency_in_flight
              - idempotency_key_reuse
              - domain_tld_not_allowed
              - domain_free_host
              - domain_txt_not_found
              - rate_limited
              - merchant_rate_limited
              - operator_register_cap_exceeded
              - ticket_open_cap
              - payer_velocity_limit
              - platform_shutdown
              - service_unavailable
              - attachment_unavailable
              - agents_disabled
              - upstream_error
              - operator_oauth_failed
              - internal_error
            message:
              type: string
              description: Human-readable English message for the code.
            request_id:
              type: string
              description: Request correlation id — also returned on EVERY response (success included) as the X-Request-Id header. Quote it in support requests.
            retry_after:
              type: integer
              description: Seconds to wait before retrying. Present on every 429, 503 and 409 idempotency_in_flight; mirrored in the Retry-After HTTP header.
            docs_url:
              type: string
              description: Link to the error documentation.
            details:
              type: object
              description: 'Optional machine-readable extras, normative per code: validation_error → {field}; insufficient_scope → {required_scope}; rate_limited → {scope}; amount_out_of_range → {min_cents, max_cents} (bounds of THIS endpoint/mode); account_limit_exceeded → {limit, limit_cents, used_cents?} for the legacy per-account limits, and {limit: "receive_cap", current_level, cap_cents, used_cents, amount_cents, window_days, resets_at, next_level_requirements, kyc_url, concurrent?} for the receive cap; key_limit_exceeded → {limit, limit_cents, used_cents}; payer_velocity_limit → {window_minutes, max_per_window}; operator_register_cap_exceeded → {scope, max_per_window, window_hours}; ticket_open_cap → {max_open}; agent_signature_expired → {server_time}; discount_changed → {discount_pct, amount_cents} (the merchant''s current values); the verification_* codes → {missing, remaining} (same shape as GET /api/verification); first_withdraw_tax_number_mismatch → {anchor_tax_number} (masked).'
              additionalProperties: false
              properties:
                server_time:
                  type: integer
                  description: Server unix time in seconds (agent_signature_expired) — re-sync the client clock and retry.
                field:
                  type: string
                  description: Offending request field (validation_error).
                max_open:
                  type: integer
                  description: Maximum open tickets allowed for this account (ticket_open_cap).
                required_scope:
                  type: string
                  description: Scope the API key is missing (insufficient_scope).
                scope:
                  type: string
                  description: Rate-limit scope that tripped (rate_limited).
                window_minutes:
                  type: integer
                  description: Sliding-window length in minutes (payer_velocity_limit).
                window_hours:
                  type: integer
                  description: Rolling-window length in hours (operator_register_cap_exceeded).
                max_per_window:
                  type: integer
                  description: 'Maximum inside the window: QRs per payer CPF/CNPJ (payer_velocity_limit), or agent registrations per operator token (operator_register_cap_exceeded).'
                limit:
                  type: string
                  description: 'Which limit tripped: "receive_cap" | "first_deposit" | "per_tx" (account_limit_exceeded) or "per_tx" | "daily" (key_limit_exceeded). "cumulative" was removed on 2026-07-31 with the lifetime cap it reported.'
                limit_cents:
                  type: integer
                  description: The limit value in cents.
                used_cents:
                  type: integer
                  description: Amount already consumed against the limit, in cents (cumulative/daily limits, and the receive cap).
                current_level:
                  type: integer
                  description: Account tier the cap came from (receive_cap).
                cap_cents:
                  type: integer
                  description: The account's receive cap for the window, in cents (receive_cap).
                amount_cents:
                  type: integer
                  description: The amount that would be due now, in cents — at the current discount (discount_changed), or the refused amount (receive_cap).
                window_days:
                  type: integer
                  description: Length of the rolling receive window, in days (receive_cap).
                resets_at:
                  type:
                  - string
                  - 'null'
                  description: When the OLDEST counted amount leaves the rolling window, i.e. when part of the cap frees up (receive_cap). Null when nothing is counted — there is nothing to wait for.
                next_level_requirements:
                  type:
                  - object
                  - 'null'
                  description: What the next tier requires (receive_cap). Null at the top tier. Age and volume only — never a client count.
                  additionalProperties: false
                  properties:
                    level:
                      type: integer
                      description: The next tier.
                    min_age_days:
                      type:
                      - integer
                      - 'null'
                      description: Minimum account age, in days.
                    min_volume_cents:
                      type:
                      - integer
                      - 'null'
                      description: Minimum settled volume, in cents.
                kyc_url:
                  type:
                  - string
                  - 'null'
                  description: Where to arrange a manually raised cap (receive_cap). Null when that route is unavailable.
                concurrent:
                  type: boolean
                  description: Present and true when the refusal came from simultaneous requests rather than from amounts already settled (receive_cap) — retrying after the sibling requests finish may succeed.
                anchor_tax_number:
                  type:
                  - string
                  - 'null'
                  description: MASKED CPF/CNPJ the account's first withdrawal must be addressed to (first_withdraw_tax_number_mismatch) — the document that paid the first completed deposit. Masked (•••••••8909) because it is there for the owner to RECOGNISE, not for a caller to read off.
                min_cents:
                  type: integer
                  description: Minimum accepted amount in cents for this endpoint/mode.
                max_cents:
                  type: integer
                  description: Maximum accepted amount in cents for this endpoint/mode.
                discount_pct:
                  type: integer
                  description: The merchant's CURRENT DePix discount (discount_changed) — re-render the price from it and retry.
                missing:
                  type: array
                  description: What is still blocking account verification (the verification_* codes) — identical to the `missing` array of GET /api/verification.
                  items:
                    type: string
                    description: One blocking reason.
                    enum:
                    - verification_disabled
                    - account_age
                    - deposit_leg
                    - withdraw_leg
                    - domain_proof
                    - account_blocked
                    - tax_number_in_use
                remaining:
                  type: object
                  description: How much is left on each verification requirement (the verification_* codes) — identical to the `remaining` object of GET /api/verification.
                  required:
                  - deposit_cents
                  - withdraw_cents
                  - account_age_days
                  additionalProperties: false
                  properties:
                    deposit_cents:
                      type:
                      - integer
                      - 'null'
                      description: Still to receive from one document, in cents.
                    withdraw_cents:
                      type:
                      - integer
                      - 'null'
                      description: Still to withdraw back to it, in cents.
                    account_age_days:
                      type:
                      - integer
                      - 'null'
                      description: Days the account still has to wait.
                next_action:
                  type: object
                  description: The ONE move that unblocks this error, for a caller acting without a human in the loop. At most one per error; `kind` is a closed vocabulary. Absent on codes where the only answer is to fix the request itself, and on the anonymous payer endpoints (every action here addresses the account owner).
                  required:
                  - kind
                  additionalProperties: false
                  properties:
                    kind:
                      type: string
                      description: call_tool = call the named tool; human_step = a person must open the URL and do something; http_call = call the named endpoint; wait = retry after retry_after_seconds; reconnect = re-authorise the connector.
                      enum:
                      - call_tool
                      - human_step
                      - http_call
                      - wait
                      - reconnect
                    tool:
                      type: string
                      description: Tool to call (kind=call_tool).
                    url:
                      type: string
                      description: URL a person opens (kind=human_step) or an endpoint to call (kind=http_call).
                    retry_after_seconds:
                      type: integer
                      description: Seconds to wait (kind=wait). Mirrors error.retry_after and the Retry-After header when the response carries one — never a third, disagreeing deadline.
    HealthResponse:
      type: object
      description: 'Dependency health. The HTTP status is the contract: 200 = healthy, 503 = degraded.'
      required:
      - status
      - turso
      - redis
      - schema
      - timestamp
      additionalProperties: false
      properties:
        status:
          type: string
          enum:
          - ok
          - degraded
          description: '"ok" when every dependency check passed, "degraded" otherwise (mirrors the HTTP status).'
        turso:
          type: boolean
          description: Database reachability.
        redis:
          type: boolean
          description: Rate-limit store reachability.
        schema:
          type: boolean
          description: Schema migration probe.
        timestamp:
          type: string
          description: Server time (ISO 8601).
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: 'API key in the Authorization header: `Authorization: Bearer sk_live_…` (production) or `Bearer sk_test_…` (sandbox). Keys are created per merchant in the dashboard with explicit scopes (merchant_read/merchant_write/wallet_read/wallet_write) and, for wallet_write keys, mandatory spending limits. First-party dashboard JWTs are also accepted on the same endpoints.'
x-refined-from:
- depixapp-com-openapi.json
- depixapp-com-openapi.yml