openapi: 3.0.3
info:
  title: Panadata API v4
  description: |
    REST API for accessing Panama public registry data. Returns entity details
    (organizations and natural persons) with optional data sections controlled
    by product codes.

    ## Billing

    Every authenticated request starts with a **$0.01** base charge. When the
    `include` query parameter is used on the detail endpoint, the requested
    product code prices are added on top. In the platform UI, this consumption is
    deducted from a prepaid balance. Billing occurs **after** the request succeeds
    (2xx responses only).

    Product codes use smart resolution: codes are sorted by data level count descending
    and only non-redundant codes are charged. For example, requesting
    `?include=DAT-CORE,CHK-BIN` charges only DAT-CORE because it already covers
    the `core_registro` level provided by CHK-BIN.
  version: 4.0.0

servers:
  - url: https://api.panadata.net
    description: Production

security:
  - BearerAuth: []

x-product-codes:
  CHK-BIN:
    cost: 0.02
    description: Binary existence check. Returns the basic identifiers (id and panadata_id), plus nombre and ruc/cedula.
    tags: [core_registro]
  DAT-CORE:
    cost: 0.15
    tags: [core_registro, contacto, entity_events]
  DAT-HOOK:
    cost: 0.03
    tags: [entity_events]
  DAT-GOV:
    cost: 0.15
    tags: [directores, suspension, organizaciones, representante_legal_identificado, gacetas, documentos_contraloria, is_itbm, last_itbm_date, funcionario]
  DAT-BIZ:
    cost: 0.08
    tags: [avisos, licencias, personal_licenses, company_licenses, fideicomisos, marcas]
  DAT-ASSET:
    cost: 0.25
    tags: [propiedades, fincas, bienes_muebles, naves]
  DAT-TRADE:
    cost: 0.20
    tags: [importaciones, exportaciones, imports_summary, exports_summary, customs_summary]
  DAT-DOC:
    cost: 0.06
    tags: [documentos_escaneados, documentos_digitales, rp_report_url]
  DAT-RISK:
    cost: 0.20
    tags: [css_moroso_menciones, sanciones, idoneidades, expedientes_judiciales]
  DAT-PROC:
    cost: 0.05
    tags: [licitaciones]
  DAT-NEWS:
    cost: 0.12
    tags: [noticias, noticias_globales]
  DAT-LEGAL:
    cost: 0.10
    tags: [migrations, work_permits]
  DAT-CGR:
    cost: TBD
    tags: [documentos_contraloria, fideicomisos]
  DAT-IP:
    cost: TBD
    tags: [marcas]
  DAT-LABOR:
    cost: TBD
    tags: [migrations, work_permits, funcionario]
  DAT-SCREEN:
    cost: TBD
    tags: [funcionario, sanciones_internacionales]
  DAT-ALL:
    cost: 1.35
    tags:
      - core_registro
      - contacto
      - entity_events
      - directores
      - suspension
      - organizaciones
      - representante_legal_identificado
      - avisos
      - licencias
      - personal_licenses
      - company_licenses
      - propiedades
      - fincas
      - bienes_muebles
      - naves
      - importaciones
      - exportaciones
      - imports_summary
      - exports_summary
      - customs_summary
      - documentos_escaneados
      - documentos_digitales
      - css_moroso_menciones
      - sanciones
      - idoneidades
      - expedientes_judiciales
      - licitaciones
      - gacetas
      - documentos_contraloria
      - is_itbm
      - last_itbm_date
      - funcionario
      - fideicomisos
      - marcas
      - noticias
      - noticias_globales
      - migrations
      - work_permits
      - rp_report_url
  DAT-ALL+:
    cost: TBD
    tags: [all tags with full historical depth]

paths:
  /health:
    get:
      operationId: healthCheck
      summary: Health check
      description: Returns service health status. No authentication required.
      security: []
      responses:
        "200":
          description: Service is healthy.
          content:
            application/json:
              schema:
                type: object
                required: [status, service]
                properties:
                  status:
                    type: string
                    example: ok
                  service:
                    type: string
                    example: panadata-api

  /v4/panama/entidades/{id}:
    get:
      operationId: getEntity
      summary: Get entity detail
      description: |
        Returns full detail for an organization or natural person. Use this
        endpoint after selecting the correct `id` from search results. The
        detail response also includes `panadata_id`.

        The
        `include` query parameter is **required** — it specifies which product
        code(s) to request. The minimum product code is `CHK-BIN` (binary
        existence check), which returns only the entity's basic identifiers:
        `id`, `nombre`, `ruc` or `cedula`, and `panadata_id`.

        ### Product codes

        | Code | Cost | Tags |
        |------|------|------|
        | CHK-BIN | 0.02 | Binary existence check. Returns: id, nombre, ruc/cedula, panadata_id |
        | DAT-CORE | 0.15 | core_registro, contacto, entity_events |
        | DAT-HOOK | 0.03 | entity_events |
        | DAT-GOV | 0.15 | directores, suspension, organizaciones, representante_legal_identificado, gacetas, documentos_contraloria, is_itbm, last_itbm_date, funcionario |
        | DAT-BIZ | 0.08 | avisos, licencias, personal_licenses, company_licenses, fideicomisos, marcas |
        | DAT-ASSET | 0.25 | propiedades, fincas, bienes_muebles, naves |
        | DAT-TRADE | 0.20 | importaciones, exportaciones, imports_summary, exports_summary, customs_summary |
        | DAT-DOC | 0.06 | documentos_escaneados, documentos_digitales, rp_report_url |
        | DAT-RISK | 0.20 | css_moroso_menciones, sanciones, idoneidades, expedientes_judiciales |
        | DAT-PROC | 0.05 | licitaciones |
        | DAT-NEWS | 0.12 | noticias, noticias_globales |
        | DAT-LEGAL | 0.10 | migrations, work_permits |
        | DAT-CGR | TBD | documentos_contraloria, fideicomisos |
        | DAT-IP | TBD | marcas |
        | DAT-LABOR | TBD | migrations, work_permits, funcionario |
        | DAT-SCREEN | TBD | funcionario, sanciones_internacionales |
        | DAT-ALL | 1.35 | all tags |
        | DAT-ALL+ | TBD | all tags with full historical depth |

        Total cost = base ($0.01) + sum of charged product code prices.
      parameters:
        - name: id
          in: path
          required: true
          description: Entity ID (integer).
          schema:
            type: integer
        - name: include
          in: query
          required: true
          description: |
            Comma-separated product codes to include data sections. Required.
            The minimum is `CHK-BIN` for a binary existence check.
            Example: `DAT-CORE,DAT-GOV`
          schema:
            type: string
          example: DAT-CORE,DAT-GOV
      responses:
        "200":
          description: Entity detail. Shape depends on entity type (organization or natural person).
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/OrganizationDetail"
                  - $ref: "#/components/schemas/NaturalPersonDetail"
        "400":
          description: Invalid ID, missing include parameter, or unknown product code.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalidId:
                  summary: Invalid entity ID
                  value:
                    error: "id must be an integer"
                unknownCode:
                  summary: Unknown product code
                  value:
                    error: "unknown product code(s): INVALID-CODE"
        "401":
          description: Missing Authorization header.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GatewayUnauthorizedError"
              example:
                message: "Unauthorized"
        "403":
          description: API key rejected by the authentication layer.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GatewayForbiddenError"
              example:
                Message: "User is not authorized to access this resource with an explicit deny in an identity-based policy"
        "402":
          description: Insufficient prepaid balance.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: "insufficient credits"
        "404":
          description: Entity not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: "entity not found"

  /v4/panama/entidades:
    get:
      operationId: searchEntities
      summary: Search entities
      description: |
        Search organizations and natural persons by name and/or RUC. At least
        one of `nombre` or `ruc` is required. Returns up to 20 results.
        Use the returned `id` in `GET /v4/panama/entidades/{id}`.

        Cost: $0.01 per request.
      parameters:
        - name: nombre
          in: query
          required: false
          description: Entity name to search for.
          schema:
            type: string
          example: Panadata
        - name: ruc
          in: query
          required: false
          description: RUC number to search for.
          schema:
            type: string
          example: "155640453"
      responses:
        "200":
          description: Search results.
          content:
            application/json:
              schema:
                type: object
                required: [results]
                properties:
                  results:
                    type: array
                    maxItems: 20
                    items:
                      $ref: "#/components/schemas/EntitySummary"
        "400":
          description: Missing required query parameters.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: "at least one of 'nombre' or 'ruc' is required"
        "401":
          description: Missing Authorization header.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GatewayUnauthorizedError"
              example:
                message: "Unauthorized"
        "403":
          description: API key rejected by the authentication layer.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GatewayForbiddenError"
              example:
                Message: "User is not authorized to access this resource with an explicit deny in an identity-based policy"
        "402":
          description: Insufficient prepaid balance.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: "insufficient credits"

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: |
        API key prefixed with `pk_`. Pass as `Authorization: Bearer pk_...`.

  schemas:
    # ------------------------------------------------------------------
    # Entity detail schemas
    # ------------------------------------------------------------------
    OrganizationDetail:
      title: "Organization Detail"
      type: object
      description: |
        Detail for an organization entity. Base fields are always returned and
        correspond to the `core_registro` tag, covered by `CHK-BIN` and also by
        `DAT-CORE`. Tag properties are only present when the corresponding product code
        is requested via the `include` parameter.
      required: [id, panadata_id, sid, nombre]
      properties:
        id:
          type: integer
        panadata_id:
          type: integer
          description: Stable public identifier for the entity (currently equal to id).
        sid:
          type: string
        nombre:
          type: string
          nullable: true
        ficha:
          type: string
          nullable: true
        folio:
          type: string
          nullable: true
        ruc:
          type: string
          nullable: true
        ruc_no_dv:
          type: string
          nullable: true
        tipo_organizacion:
          type: string
          nullable: true
        fecha_registro:
          type: string
          nullable: true
        capital:
          type: string
          nullable: true
        domicilio:
          type: string
          nullable: true
        status:
          type: string
          nullable: true
        vigencia:
          type: string
          nullable: true
        source_updated_at:
          type: string
          nullable: true
          description: ISO 8601 timestamp of last source update.
        # --- tag properties (included via product codes) ---
        contacto:
          description: "Tag: contacto (DAT-CORE). Contact information from derived data."
          type: object
          nullable: true
        entity_events:
          description: "Tag: entity_events (DAT-CORE, DAT-HOOK). Recent entity events, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/EntityEvent"
        directores:
          description: "Tag: directores (DAT-GOV). Board of directors from entity data."
          type: array
          nullable: true
          items:
            type: object
        suspension:
          description: "Tag: suspension (DAT-GOV). Suspension status from derived data."
          type: object
          nullable: true
        organizaciones:
          description: "Tag: organizaciones (DAT-GOV). Organization memberships, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/OrganizationMembership"
        representante_legal_identificado:
          description: "Tag: representante_legal_identificado (DAT-GOV). Legal representative from derived data."
          type: object
          nullable: true
        gacetas:
          description: "Tag: gacetas (DAT-GOV). Official gazette mentions, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/Gaceta"
        documentos_contraloria:
          description: "Tag: documentos_contraloria (DAT-GOV). Comptroller documents, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/ContraloriaDoc"
        is_itbm:
          description: "Tag: is_itbm (DAT-GOV). ITBM tax status."
          type: boolean
          nullable: true
        last_itbm_date:
          description: "Tag: last_itbm_date (DAT-GOV). Last ITBM filing date."
          type: string
          nullable: true
        funcionario:
          description: "Tag: funcionario (DAT-GOV). Public employee payroll records, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/Planilla"
        avisos:
          description: "Tag: avisos (DAT-BIZ). Business operation notices, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/BusinessNotice"
        licencias:
          description: "Tag: licencias (DAT-BIZ). General licenses, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/GeneralLicense"
        personal_licenses:
          description: "Tag: personal_licenses (DAT-BIZ). Personal/professional licenses, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/PersonalLicense"
        company_licenses:
          description: "Tag: company_licenses (DAT-BIZ). Company licenses, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/CompanyLicense"
        fideicomisos:
          description: "Tag: fideicomisos (DAT-BIZ). Trusts, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/Fideicomiso"
        marcas:
          description: "Tag: marcas (DAT-BIZ). Trademarks, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/Marca"
        propiedades:
          description: "Tag: propiedades (DAT-ASSET). Horizontal property units, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/Propiedad"
        fincas:
          description: "Tag: fincas (DAT-ASSET). Land parcels, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/Finca"
        bienes_muebles:
          description: "Tag: bienes_muebles (DAT-ASSET). Movable assets, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/BienMueble"
        naves:
          description: "Tag: naves (DAT-ASSET). Vessels, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/Nave"
        importaciones:
          description: "Tag: importaciones (DAT-TRADE). Import records, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/Importacion"
        exportaciones:
          description: "Tag: exportaciones (DAT-TRADE). Export records, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/Exportacion"
        imports_summary:
          description: "Tag: imports_summary (DAT-TRADE). Aggregated import statistics from derived data."
          type: object
          nullable: true
        exports_summary:
          description: "Tag: exports_summary (DAT-TRADE). Aggregated export statistics from derived data."
          type: object
          nullable: true
        customs_summary:
          description: "Tag: customs_summary (DAT-TRADE). Combined import and export summaries."
          type: object
          nullable: true
          properties:
            imports:
              type: object
              nullable: true
            exports:
              type: object
              nullable: true
            recent_exports_summary:
              type: object
              nullable: true
            recent_imports_summary:
              type: object
              nullable: true
            export_tariff_activity_similarity:
              type: object
              nullable: true
            import_tariff_activity_similarity:
              type: object
              nullable: true
        documentos_escaneados:
          description: "Tag: documentos_escaneados (DAT-DOC). Scanned documents, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/DocumentoEscaneado"
        documentos_digitales:
          description: "Tag: documentos_digitales (DAT-DOC). Digital documents, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/DocumentoDigital"
        rp_report_url:
          description: "Tag: rp_report_url (DAT-DOC). Presigned S3 URL for registry report."
          type: string
          nullable: true
        css_moroso_menciones:
          description: "Tag: css_moroso_menciones (DAT-RISK). CSS delinquent debtor mentions, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/CSSMorosoMencion"
        sanciones:
          description: "Tag: sanciones (DAT-RISK). Sanctions, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/Sancion"
        idoneidades:
          description: "Tag: idoneidades (DAT-RISK). Professional certifications, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/Idoneidad"
        expedientes_judiciales:
          description: "Tag: expedientes_judiciales (DAT-RISK). Court cases, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/ExpedienteJudicial"
        licitaciones:
          description: "Tag: licitaciones (DAT-PROC). Public procurement bids, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/Licitacion"
        noticias:
          description: "Tag: noticias (DAT-NEWS). News mentions, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/Noticia"
        noticias_globales:
          description: "Tag: noticias_globales (DAT-NEWS). International news mentions, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/Noticia"
        migrations:
          description: "Tag: migrations (DAT-LEGAL). Migration records, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/Migration"
        work_permits:
          description: "Tag: work_permits (DAT-LEGAL). Work permits, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/WorkPermit"

    NaturalPersonDetail:
      title: "Natural Person Detail"
      type: object
      description: |
        Detail for a natural person entity. Base fields are always returned and
        correspond to the `core_registro` tag, covered by `CHK-BIN` and also by
        `DAT-CORE`. Tag properties are only present when the corresponding product code
        is requested via the `include` parameter.

        Natural persons do not support the following tags: contacto,
        directores, suspension, representante_legal_identificado,
        customs_summary, is_itbm, last_itbm_date, rp_report_url.
      required: [id, panadata_id, sid, nombre]
      properties:
        id:
          type: integer
        panadata_id:
          type: integer
          description: Stable public identifier for the entity (currently equal to id).
        sid:
          type: string
        nombre:
          type: string
          nullable: true
        cedula:
          type: string
          nullable: true
        # --- tag properties (included via product codes) ---
        entity_events:
          description: "Tag: entity_events (DAT-CORE, DAT-HOOK). Recent entity events, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/EntityEvent"
        organizaciones:
          description: "Tag: organizaciones (DAT-GOV). Organization memberships, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/OrganizationMembership"
        gacetas:
          description: "Tag: gacetas (DAT-GOV). Official gazette mentions, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/Gaceta"
        documentos_contraloria:
          description: "Tag: documentos_contraloria (DAT-GOV). Comptroller documents, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/ContraloriaDoc"
        funcionario:
          description: "Tag: funcionario (DAT-GOV). Public employee payroll records, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/Planilla"
        avisos:
          description: "Tag: avisos (DAT-BIZ). Business operation notices, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/BusinessNotice"
        licencias:
          description: "Tag: licencias (DAT-BIZ). General licenses, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/GeneralLicense"
        personal_licenses:
          description: "Tag: personal_licenses (DAT-BIZ). Personal/professional licenses, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/PersonalLicense"
        company_licenses:
          description: "Tag: company_licenses (DAT-BIZ). Company licenses, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/CompanyLicense"
        fideicomisos:
          description: "Tag: fideicomisos (DAT-BIZ). Trusts, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/Fideicomiso"
        marcas:
          description: "Tag: marcas (DAT-BIZ). Trademarks, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/Marca"
        propiedades:
          description: "Tag: propiedades (DAT-ASSET). Horizontal property units, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/Propiedad"
        fincas:
          description: "Tag: fincas (DAT-ASSET). Land parcels, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/Finca"
        bienes_muebles:
          description: "Tag: bienes_muebles (DAT-ASSET). Movable assets, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/BienMueble"
        naves:
          description: "Tag: naves (DAT-ASSET). Vessels, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/Nave"
        importaciones:
          description: "Tag: importaciones (DAT-TRADE). Import records, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/Importacion"
        exportaciones:
          description: "Tag: exportaciones (DAT-TRADE). Export records, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/Exportacion"
        imports_summary:
          description: "Tag: imports_summary (DAT-TRADE). Aggregated import statistics from derived data."
          type: object
          nullable: true
        exports_summary:
          description: "Tag: exports_summary (DAT-TRADE). Aggregated export statistics from derived data."
          type: object
          nullable: true
        documentos_escaneados:
          description: "Tag: documentos_escaneados (DAT-DOC). Scanned documents, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/DocumentoEscaneado"
        documentos_digitales:
          description: "Tag: documentos_digitales (DAT-DOC). Digital documents, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/DocumentoDigital"
        css_moroso_menciones:
          description: "Tag: css_moroso_menciones (DAT-RISK). CSS delinquent debtor mentions, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/CSSMorosoMencion"
        sanciones:
          description: "Tag: sanciones (DAT-RISK). Sanctions, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/Sancion"
        idoneidades:
          description: "Tag: idoneidades (DAT-RISK). Professional certifications, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/Idoneidad"
        expedientes_judiciales:
          description: "Tag: expedientes_judiciales (DAT-RISK). Court cases, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/ExpedienteJudicial"
        licitaciones:
          description: "Tag: licitaciones (DAT-PROC). Public procurement bids, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/Licitacion"
        noticias:
          description: "Tag: noticias (DAT-NEWS). News mentions, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/Noticia"
        noticias_globales:
          description: "Tag: noticias_globales (DAT-NEWS). International news mentions, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/Noticia"
        migrations:
          description: "Tag: migrations (DAT-LEGAL). Migration records, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/Migration"
        work_permits:
          description: "Tag: work_permits (DAT-LEGAL). Work permits, max 100."
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/WorkPermit"

    # ------------------------------------------------------------------
    # Search result schema
    # ------------------------------------------------------------------
    EntitySummary:
      title: "Entity Summary"
      type: object
      required: [id, nombre, type]
      properties:
        id:
          type: integer
          description: Use this ID in `GET /v4/panama/entidades/{id}`. The detail response also includes `panadata_id`.
        nombre:
          type: string
          nullable: true
        ruc_no_dv:
          type: string
          nullable: true
        type:
          type: string
          description: Entity type identifier (e.g. "Organization", "NaturalPerson").

    # ------------------------------------------------------------------
    # Tag item schemas
    # ------------------------------------------------------------------
    EntityEvent:
      title: "Entity Event"
      type: object
      properties:
        id:
          type: integer
        asset_type:
          type: string
          nullable: true
        asset_id:
          type: integer
          nullable: true
        event_action:
          type: string
          nullable: true
        asset_snapshot:
          type: object
          nullable: true
        asset_event_date:
          type: string
          nullable: true
          description: Date string (ISO 8601).

    OrganizationMembership:
      title: "Organization Membership"
      type: object
      properties:
        cargo:
          type: string
          nullable: true
        nombre:
          type: string
          nullable: true
        organization_id:
          type: integer
          nullable: true
        activo:
          type: boolean
          nullable: true

    BusinessNotice:
      title: "Business Notice"
      type: object
      properties:
        numero:
          type: string
          nullable: true
        nombre:
          type: string
          nullable: true
        ruc:
          type: string
          nullable: true
        estatus:
          type: string
          nullable: true
        fecha_generacion:
          type: string
          nullable: true

    GeneralLicense:
      title: "General License"
      type: object
      properties:
        id:
          type: string
          nullable: true
        nombre:
          type: string
          nullable: true
        activo:
          type: boolean
          nullable: true

    PersonalLicense:
      title: "Personal License"
      type: object
      properties:
        id:
          type: string
          nullable: true
        nombre:
          type: string
          nullable: true
        idoneidad:
          type: string
          nullable: true
        activo:
          type: boolean
          nullable: true

    CompanyLicense:
      title: "Company License"
      type: object
      properties:
        id:
          type: string
          nullable: true
        nombre:
          type: string
          nullable: true

    Propiedad:
      title: "Property"
      type: object
      properties:
        id:
          type: integer
        folio:
          type: string
          nullable: true
        ficha:
          type: string
          nullable: true
        edificio:
          type: string
          nullable: true
        fecha_inscripcion:
          type: string
          nullable: true
        hipotecas:
          type: array
          items:
            $ref: "#/components/schemas/RealEstateElemento"
        compraventas:
          type: array
          items:
            $ref: "#/components/schemas/RealEstateElemento"
        last_hipoteca:
          $ref: "#/components/schemas/RealEstateElemento"
          nullable: true
        last_compraventa:
          $ref: "#/components/schemas/RealEstateElemento"
          nullable: true
        record_events:
          type: array
          maxItems: 25
          items:
            $ref: "#/components/schemas/RealEstateElemento"

    Finca:
      title: "Land Parcel"
      type: object
      properties:
        id:
          type: integer
        folio:
          type: string
          nullable: true
        ficha:
          type: string
          nullable: true
        fecha_inscripcion:
          type: string
          nullable: true
        hipotecas:
          type: array
          items:
            $ref: "#/components/schemas/RealEstateElemento"
        compraventas:
          type: array
          items:
            $ref: "#/components/schemas/RealEstateElemento"
        last_hipoteca:
          $ref: "#/components/schemas/RealEstateElemento"
          nullable: true
        last_compraventa:
          $ref: "#/components/schemas/RealEstateElemento"
          nullable: true
        record_events:
          type: array
          maxItems: 25
          items:
            $ref: "#/components/schemas/RealEstateElemento"

    BienMueble:
      title: "Movable Asset"
      type: object
      properties:
        id:
          type: integer
        folio:
          type: string
          nullable: true
        ficha:
          type: string
          nullable: true
        fecha_inscripcion:
          type: string
          nullable: true
        propietario_panadata_string:
          type: string
          nullable: true

    Nave:
      title: "Vessel"
      type: object
      properties:
        id:
          type: integer
        nombre:
          type: string
          nullable: true
        ficha:
          type: string
          nullable: true
        fecha_registro:
          type: string
          nullable: true

    Importacion:
      title: "Import Record"
      type: object
      properties:
        id:
          type: integer
        descripcion:
          type: string
          nullable: true
        fraccion_arancelaria:
          type: string
          nullable: true
        puerto_entrada:
          type: string
          nullable: true
        procedencia:
          type: string
          nullable: true
        fecha:
          type: string
          nullable: true
        valor_cif:
          type: number
          nullable: true

    Exportacion:
      title: "Export Record"
      type: object
      properties:
        id:
          type: integer
        descripcion:
          type: string
          nullable: true
        fraccion_arancelaria:
          type: string
          nullable: true
        puerto_salida:
          type: string
          nullable: true
        destino:
          type: string
          nullable: true
        fecha:
          type: string
          nullable: true
        valor_cif:
          type: number
          nullable: true

    DocumentoEscaneado:
      title: "Scanned Document"
      type: object
      properties:
        id:
          type: integer
        nombre:
          type: string
          nullable: true
        pdf_url:
          type: string
          nullable: true

    DocumentoDigital:
      title: "Digital Document"
      type: object
      properties:
        id:
          type: integer
        entrada:
          type: string
          nullable: true
        detalle:
          type: string
          nullable: true
        fecha_ingreso:
          type: string
          nullable: true
        fecha_escritura:
          type: string
          nullable: true

    CSSMorosoMencion:
      title: "CSS Delinquent Mention"
      type: object
      properties:
        id:
          type: integer
        titulo:
          type: string
          nullable: true
        fecha_publicacion:
          type: string
          nullable: true

    Sancion:
      title: "Sanction"
      type: object
      properties:
        id:
          type: integer
        nombre:
          type: string
          nullable: true
        tipo_sancion:
          type: string
          nullable: true

    Idoneidad:
      title: "Professional License"
      type: object
      properties:
        id:
          type: string
          nullable: true
        nombre:
          type: string
          nullable: true
        idoneidad:
          type: string
          nullable: true

    ExpedienteJudicial:
      title: "Court Case"
      type: object
      properties:
        id:
          type: integer
        rue:
          type: string
          nullable: true
        partes:
          type: string
          nullable: true
        tipo_negocio:
          type: string
          nullable: true
        fecha_reparto:
          type: string
          nullable: true

    Licitacion:
      title: "Public Procurement"
      type: object
      properties:
        id:
          type: integer
        acto:
          type: string
          nullable: true
        descripcion:
          type: string
          nullable: true
        entidad:
          type: string
          nullable: true
        estado:
          type: string
          nullable: true
        fecha_publicacion:
          type: string
          nullable: true
        licitacion_url:
          type: string
          nullable: true
          description: Direct link to the PanamaCompra tender page.
        documentos:
          type: array
          description: Attached documents with PDF links.
          items:
            type: object
            properties:
              nombre:
                type: string
                nullable: true
              pdf_url:
                type: string
                nullable: true

    Gaceta:
      title: "Official Gazette"
      type: object
      properties:
        id:
          type: integer
        sid:
          type: string
          nullable: true
        gaceta:
          type: string
          nullable: true
        entidad:
          type: string
          nullable: true
        titulo:
          type: string
          nullable: true
        descripcion:
          type: string
          nullable: true
        gaceta_url:
          type: string
          nullable: true
          description: Link to the gazette document.
        pdf_url:
          type: string
          nullable: true
          description: Link to the gazette PDF.
        publicacion_id:
          type: string
          nullable: true
        fecha_publicacion:
          type: string
          nullable: true
        fecha_redactacion:
          type: string
          nullable: true
        source_updated_at:
          type: string
          nullable: true

    Noticia:
      title: "News Mention"
      type: object
      properties:
        id:
          type: integer
        sid:
          type: string
          nullable: true
        titulo:
          type: string
          nullable: true
        fuente:
          type: string
          nullable: true
        url:
          type: string
          nullable: true
        fecha:
          type: string
          nullable: true
        resumen:
          type: string
          nullable: true
        source_updated_at:
          type: string
          nullable: true

    Fideicomiso:
      title: "Trust"
      type: object
      properties:
        id:
          type: integer
        sid:
          type: string
          nullable: true
        ficha:
          type: string
          nullable: true
        folio:
          type: string
          nullable: true
        fecha_inscripcion:
          type: string
          nullable: true
        rol:
          type: string
          nullable: true
        source_updated_at:
          type: string
          nullable: true

    Migration:
      title: "Migration Record"
      type: object
      properties:
        id:
          type: integer
        sid:
          type: string
          nullable: true
        numero_caso:
          type: string
          nullable: true
        nombre:
          type: string
          nullable: true
        source_updated_at:
          type: string
          nullable: true

    WorkPermit:
      title: "Work Permit"
      type: object
      properties:
        id:
          type: integer
        sid:
          type: string
          nullable: true
        numero_caso:
          type: string
          nullable: true
        nombre:
          type: string
          nullable: true
        nacionalidad:
          type: string
          nullable: true
        numero_pasaporte:
          type: string
          nullable: true
        empresa:
          type: string
          nullable: true
        source_updated_at:
          type: string
          nullable: true

    ContraloriaDoc:
      title: "Comptroller Document"
      type: object
      properties:
        id:
          type: integer
        sid:
          type: string
          nullable: true
        tramite:
          type: string
          nullable: true
        documento:
          type: string
          nullable: true
        institucion:
          type: string
          nullable: true
        favor:
          type: string
          nullable: true
        fecha_entrada:
          type: string
          nullable: true
        fecha_refrando:
          type: string
          nullable: true
        fecha_salida:
          type: string
          nullable: true
        numero:
          type: string
          nullable: true
        scafid:
          type: string
          nullable: true
        monto:
          type: number
          nullable: true
        estado:
          type: string
          nullable: true
        asunto:
          type: string
          nullable: true
        source_updated_at:
          type: string
          nullable: true

    Marca:
      title: "Trademark"
      type: object
      properties:
        id:
          type: integer
        sid:
          type: string
          nullable: true
        solicitud:
          type: string
          nullable: true
        nombre:
          type: string
          nullable: true
        abogado:
          type: string
          nullable: true
        titulares:
          type: string
          nullable: true
        registro:
          type: string
          nullable: true
        fecha_solicitud:
          type: string
          nullable: true
        fecha_registro:
          type: string
          nullable: true
        fecha_vencimiento:
          type: string
          nullable: true
        estado:
          type: string
          nullable: true
        source_updated_at:
          type: string
          nullable: true

    Planilla:
      title: "Public Payroll Record"
      type: object
      properties:
        id:
          type: integer
        sid:
          type: string
          nullable: true
        nombre:
          type: string
          nullable: true
        cedula:
          type: string
          nullable: true
        institucion:
          type: string
          nullable: true
        cargo:
          type: string
          nullable: true
        fecha_inicio:
          type: string
          nullable: true
        estado:
          type: string
          nullable: true
        total:
          type: number
          nullable: true
        pep_score:
          type: number
          nullable: true
        source_updated_at:
          type: string
          nullable: true

    RealEstateElemento:
      title: "Real Estate Element"
      type: object
      properties:
        id:
          type: integer
        sid:
          type: string
          nullable: true
        nombre:
          type: string
          nullable: true
        fecha:
          type: string
          nullable: true
        hipoteca:
          type: object
          nullable: true
        compraventa:
          type: object
          nullable: true

    # ------------------------------------------------------------------
    # Error schema
    # ------------------------------------------------------------------
    GatewayUnauthorizedError:
      type: object
      required: [message]
      properties:
        message:
          type: string

    GatewayForbiddenError:
      type: object
      required: [Message]
      properties:
        Message:
          type: string

    Error:
      type: object
      required: [error]
      properties:
        error:
          type: string