Declarar Fácil Agent API

openapi: 3.2.0
info:
  title: Declararfacil Com Agent API
  version: 1.0.0
  description: 'Operations tagged Agent across 2 of this provider''s published API definitions: declararfacil-com-agent-openapi.json, declararfacil-com-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://declararfacil.com
tags:
- name: Agent
paths:
  /api/agent/v1/skill:
    get:
      summary: 'Public: the skill package (SKILL.md, mcp.json) with sha256 of each file'
      responses:
        '200':
          description: OK
      tags:
      - Agent
      operationId: getApiAgentV1Skill
      x-operation-id-source: derived
    servers:
    - url: https://declararfacil.com
  /api/agent/v1/skill/version:
    get:
      summary: 'Public: revision and file hashes'
      responses:
        '200':
          description: OK
      tags:
      - Agent
      operationId: getApiAgentV1SkillVersion
      x-operation-id-source: derived
    servers:
    - url: https://declararfacil.com
  /api/agent/v1/connect:
    post:
      summary: 'Start a connection without any credential: returns connect_url for the person…'
      security: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                client_name:
                  type: string
                  description: Your product name as the person will see it, e.g. Claude Code
      responses:
        '201':
          description: Request created; lives 30 minutes
        '429':
          description: Too many requests from this address
      tags:
      - Agent
      operationId: postApiAgentV1Connect
      x-operation-id-source: derived
    servers:
    - url: https://declararfacil.com
  /api/agent/v1/connect/{poll_secret}:
    get:
      summary: 'Poll a connection: pending, expired, approved (carries the token once, plus…'
      security: []
      parameters:
      - name: poll_secret
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Status
        '404':
          description: Unknown request
      tags:
      - Agent
      operationId: getApiAgentV1ConnectByPollSecret
      x-operation-id-source: derived
    servers:
    - url: https://declararfacil.com
  /api/agent/v1/me:
    get:
      summary: 'Who the caller is: profile, steps (account, agent, profile, subscription)…'
      security:
      - linkToken: []
      responses:
        '200':
          description: OK
        '401':
          description: 'invalid_token: unknown or replaced token; start a new connection with POST /api/agent/v1/connect'
        '402':
          description: 'subscription_required: no active subscription; the body carries subscribe_url, steps, next_step and tell_the_user'
      tags:
      - Agent
      operationId: getApiAgentV1Me
      x-operation-id-source: derived
    servers:
    - url: https://declararfacil.com
  /api/agent/v1/extraction-spec:
    get:
      summary: Prompt, JSON schema and rules for a document kind
      security:
      - linkToken: []
      responses:
        '200':
          description: OK
        '401':
          description: 'invalid_token: unknown or replaced token; start a new connection with POST /api/agent/v1/connect'
        '402':
          description: 'subscription_required: no active subscription; the body carries subscribe_url, steps, next_step and tell_the_user'
      parameters:
      - name: kind
        in: query
        required: true
        schema:
          type: string
          enum:
          - invoice
          - bank_statement
          - modelo
          - certificate
      tags:
      - Agent
      operationId: getApiAgentV1ExtractionSpec
      x-operation-id-source: derived
    servers:
    - url: https://declararfacil.com
  /api/agent/v1/invoices/batch:
    post:
      summary: Submit up to 100 extracted invoices; per-item accepted / duplicate / rejected
      security:
      - linkToken: []
      responses:
        '200':
          description: Per-item outcome
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResult'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - invoices
              properties:
                invoices:
                  type: array
                  maxItems: 100
                  items:
                    $ref: '#/components/schemas/InvoiceInput'
      tags:
      - Agent
      operationId: postApiAgentV1InvoicesBatch
      x-operation-id-source: derived
    servers:
    - url: https://declararfacil.com
  /api/agent/v1/bank-statements:
    post:
      summary: Submit one bank statement; transactions already stored are dropped as duplicates
      security:
      - linkToken: []
      responses:
        '200':
          description: OK
        '401':
          description: 'invalid_token: unknown or replaced token; start a new connection with POST /api/agent/v1/connect'
        '402':
          description: 'subscription_required: no active subscription; the body carries subscribe_url, steps, next_step and tell_the_user'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BankStatementInput'
      tags:
      - Agent
      operationId: postApiAgentV1BankStatements
      x-operation-id-source: derived
    servers:
    - url: https://declararfacil.com
components:
  schemas:
    BatchResult:
      type: object
      properties:
        summary:
          type: object
          properties:
            total:
              type: integer
            accepted:
              type: integer
            duplicates:
              type: integer
            rejected:
              type: integer
        results:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
              status:
                type: string
                enum:
                - accepted
                - duplicate
                - rejected
              id:
                type: string
              existing_id:
                type: string
              reason:
                type: string
              reason_code:
                type: string
              matched_fields:
                type: array
                items:
                  type: string
              review_candidate:
                type: object
                additionalProperties: true
              errors:
                type: array
                items:
                  type: string
              warnings:
                type: array
                items:
                  type: string
        next_action:
          type: string
    InvoiceInput:
      type: object
      required:
      - tipo
      - fechaFactura
      - nombreClienteProveedor
      - baseImponible
      - tipoIVA
      - cuotaIVA
      - totalFactura
      properties:
        tipo:
          type: string
          enum:
          - EMITIDA
          - RECIBIDA
          description: EMITIDA = the user issued it (income). RECIBIDA = the user received it (expense).
        numeroFactura:
          type:
          - string
          - 'null'
        fechaFactura:
          type: string
          description: YYYY-MM-DD
        fechaOperacion:
          type:
          - string
          - 'null'
          description: YYYY-MM-DD when it differs from fechaFactura
        nombreClienteProveedor:
          type: string
          description: The other party (client for EMITIDA, supplier for RECIBIDA)
        nifClienteProveedor:
          type:
          - string
          - 'null'
          description: NIF/CIF/NIE or EU VAT number, as printed
        direccionCliente:
          type:
          - string
          - 'null'
        paisProveedor:
          type:
          - string
          - 'null'
          description: ISO 3166-1 alpha-2, e.g. ES, DE, US
        tipoOperacion:
          type: string
          enum:
          - NACIONAL
          - INTRACOMUNITARIA
          - EXTRACOMUNITARIA
          default: NACIONAL
        operacionB2B:
          type: boolean
          default: true
        esAdquisicionIntracomunitaria:
          type: boolean
          default: false
        esServicioNoSujeto:
          type: boolean
          default: false
        baseImponible:
          type: number
          description: Taxable base in EUR (sum of all bases if several rates; then tipoIVA is the main rate)
        tipoIVA:
          type: number
          description: 'IVA rate in percent: 21, 10, 4 or 0'
        cuotaIVA:
          type: number
          description: Printed invoice VAT amount in EUR; keep printed zero for reverse charge
        tipoIVAAutorrepercutido:
          type:
          - number
          - 'null'
          minimum: 0
          maximum: 100
          description: Applicable Spanish self-assessment rate, separately confirmed from the printed invoice rate. Never infer from printed 0%.
        fuenteTipoIVAAutorrepercutido:
          type:
          - string
          - 'null'
          description: Basis for the applicable rate, e.g. confirmed tax classification and AEAT rule. Missing basis requires review.
        porcentajeDeduccionIVA:
          type:
          - number
          - 'null'
          minimum: 0
          maximum: 100
          description: Independently confirmed VAT deduction percentage based on business use, valid evidence and applicable deduction rules. 0 means no deduction; null means unresolved. Independent of income-tax esDeducible.
        ivaAutorrepercutido:
          type:
          - number
          - 'null'
          readOnly: true
          description: 'Server result: base * self-assessment rate / 100, rounded per invoice to EUR cents; never added to the printed invoice total'
        tipoRetencion:
          type:
          - number
          - 'null'
          description: IRPF withholding rate in percent, if the invoice shows one (e.g. 15 or 7)
        cuotaRetencion:
          type:
          - number
          - 'null'
          description: IRPF withholding amount in EUR
        suplidos:
          type:
          - number
          - 'null'
          default: 0
        tipoRecargoEquivalencia:
          type:
          - number
          - 'null'
        cuotaRecargoEquivalencia:
          type:
          - number
          - 'null'
        claveRegimenEspecial:
          type:
          - string
          - 'null'
        descripcionOperacion:
          type:
          - string
          - 'null'
          description: 'One line: what was sold or bought'
        esFacturaRectificativa:
          type: boolean
          default: false
        numeroFacturaRectificada:
          type:
          - string
          - 'null'
        totalFactura:
          type: number
          description: Total to pay in EUR (base + IVA - retención + suplidos + recargo)
        categoria:
          type:
          - string
          - 'null'
          description: Expense category for RECIBIDA (e.g. SOFTWARE, ALQUILER, SUMINISTROS, MATERIAL, SERVICIOS_PROFESIONALES, TRANSPORTE, OTROS)
        esDeducible:
          type: boolean
          default: true
        notas:
          type:
          - string
          - 'null'
        confianzaOCR:
          type:
          - number
          - 'null'
          description: Your own confidence 0..1 that every amount is read correctly
        source_file:
          type:
          - string
          - 'null'
          description: Local file name, for the user's report only (never stored as a document)
    BankStatementInput:
      type: object
      required:
      - transactions
      properties:
        bankName:
          type:
          - string
          - 'null'
        bankBIC:
          type:
          - string
          - 'null'
        accountIBAN:
          type:
          - string
          - 'null'
        periodStart:
          type:
          - string
          - 'null'
          description: YYYY-MM-DD
        periodEnd:
          type:
          - string
          - 'null'
          description: YYYY-MM-DD
        openingBalance:
          type:
          - number
          - 'null'
        closingBalance:
          type:
          - number
          - 'null'
        source_file:
          type:
          - string
          - 'null'
        transactions:
          type: array
          items:
            type: object
            required:
            - date
            - concept
            - amount
            properties:
              date:
                type: string
                description: YYYY-MM-DD
              valueDate:
                type:
                - string
                - 'null'
              concept:
                type: string
                description: The statement line text, complete
              counterpartyName:
                type:
                - string
                - 'null'
              counterpartyIBAN:
                type:
                - string
                - 'null'
              amount:
                type: number
                description: Negative for debits, positive for credits, in EUR
              category:
                type:
                - string
                - 'null'
                description: SEGURIDAD_SOCIAL, COMISIONES_BANCARIAS, IMPUESTOS, ALQUILER, SUMINISTROS, OTROS, or null
              reference:
                type:
                - string
                - 'null'
  securitySchemes:
    linkToken:
      type: http
      scheme: bearer
      description: The df_ token handed out by the connect poll, or the last segment of the user's personal link (/agente/<token>).
x-refined-from:
- declararfacil-com-agent-openapi.json
- declararfacil-com-openapi.json