Facturear CUITs API

openapi: 3.2.0
info:
  title: Facturear CUITs API
  description: 'API para emitir facturas electrónicas de ARCA (Argentina) desde tu sistema: facturas, notas de crédito y débito, lotes, PDF y XML, envío por email, borradores desde documentos, webhooks y reportes. Autenticación con API Key en el header x-api-key: la key de testing opera en homologación y la de producción emite comprobantes reales.'
  version: 1.0.0
  contact:
    name: Facturear Support
    email: support@facture.ar
    url: https://facture.ar
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
- url: https://www.facture.ar/api
  description: Servidor de producción
security:
- apiKey: []
tags:
- name: CUITs
  description: CUITs emisores, sus defaults, puntos de venta y diseño
paths:
  /cuits:
    get:
      summary: Obtener CUITs
      description: Obtiene la lista de CUITs asociados a tu cuenta, con sus valores por defecto (default_pos, default_invoice_type, default_concept, default_iva, is_default).
      tags:
      - CUITs
      responses:
        '200':
          description: Lista de CUITs obtenida exitosamente
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Cuit'
        '401':
          description: No autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getCuits
      x-operation-id-source: derived
    post:
      summary: Agregar un CUIT
      description: Registra un CUIT en tu cuenta.
      tags:
      - CUITs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - number
              properties:
                number:
                  type: string
                  description: Número de CUIT
                integrationMode:
                  type: string
                  description: Modo de conexión con ARCA
      responses:
        '201':
          description: CUIT creado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cuit'
        '400':
          description: Datos inválidos
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Límite de CUITs del plan alcanzado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: El CUIT ya está registrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postCuits
      x-operation-id-source: derived
  /cuits/{cuitId}:
    get:
      summary: Obtener un CUIT
      description: Devuelve un CUIT de tu cuenta con sus datos del padrón, puntos de venta, defaults y estado de la configuración en ARCA.
      tags:
      - CUITs
      parameters:
      - name: cuitId
        in: path
        description: ID del CUIT en Facturear
        required: true
        schema:
          type: string
      responses:
        '200':
          description: CUIT
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cuit'
        '404':
          description: CUIT no encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getCuitsByCuitId
      x-operation-id-source: derived
  /cuits/{cuitId}/set-default:
    post:
      summary: Marcar como CUIT por defecto
      description: Marca este CUIT como el default de tu cuenta y desmarca los demás.
      tags:
      - CUITs
      parameters:
      - name: cuitId
        in: path
        description: ID del CUIT en Facturear o su número sin guiones
        required: true
        schema:
          type: string
      responses:
        '200':
          description: CUIT marcado
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
        '404':
          description: CUIT no encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postCuitsByCuitIdSetDefault
      x-operation-id-source: derived
  /cuits/{cuitId}/setup-status:
    get:
      summary: Estado de la configuración en ARCA
      description: En qué paso está la configuración del CUIT en ARCA.
      tags:
      - CUITs
      parameters:
      - name: cuitId
        in: path
        description: ID del CUIT en Facturear
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Estado
          content:
            application/json:
              schema:
                type: object
                properties:
                  setupStatus:
                    type: string
                    enum:
                    - INITIALIZED
                    - IN_PROGRESS
                    - TEST_CERTIFICATE_COMPLETE
                    - PROD_CERTIFICATE_COMPLETE
                    - AWAITING_DELEGATION
                    - DELEGATION_COMPLETE
                    - AUTOMATION_IN_PROGRESS
                    - AUTOMATION_FAILED
                    - COMPLETED
                    - SKIPPED
                  progress:
                    type: integer
                    minimum: 0
                    maximum: 100
                    description: 'Porcentaje: certificados, puntos de venta y concepto por defecto'
                  isCompleted:
                    type: boolean
        '404':
          description: CUIT no encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getCuitsByCuitIdSetupStatus
      x-operation-id-source: derived
  /cuits/{cuitId}/pos:
    get:
      summary: Listar puntos de venta
      description: Los puntos de venta del CUIT guardados en Facturear (la última consulta a ARCA) y la última factura emitida desde Facturear en cada uno.
      tags:
      - CUITs
      parameters:
      - name: cuitId
        in: path
        description: ID del CUIT en Facturear
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Puntos de venta
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PointsOfSale'
        '404':
          description: CUIT no encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getCuitsByCuitIdPos
      x-operation-id-source: derived
    post:
      summary: Actualizar puntos de venta desde ARCA
      description: Consulta en ARCA (producción) los puntos de venta del CUIT y los guarda. Tarda unos segundos.
      tags:
      - CUITs
      parameters:
      - name: cuitId
        in: path
        description: ID del CUIT en Facturear
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Puntos de venta actualizados
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  pos:
                    description: Respuesta de ARCA a FEParamGetPtosVenta
        '400':
          description: El CUIT no tiene puntos de venta dados de alta en ARCA
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: CUIT no encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: No se pudo consultar ARCA (por ejemplo, el CUIT no tiene certificados)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postCuitsByCuitIdPos
      x-operation-id-source: derived
  /cuits/{cuitId}/pos/last-vouchers:
    get:
      summary: Último comprobante por punto de venta
      description: Consulta en ARCA el último comprobante autorizado en cada punto de venta activo del CUIT, lo haya emitido Facturear u otro sistema. Usa el entorno de la API key y tarda unos segundos.
      tags:
      - CUITs
      parameters:
      - name: cuitId
        in: path
        description: ID del CUIT en Facturear
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Últimos comprobantes
          content:
            application/json:
              schema:
                type: object
                properties:
                  lastVouchers:
                    type: array
                    items:
                      $ref: '#/components/schemas/LastVoucher'
        '404':
          description: CUIT no encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: No se pudo consultar ARCA
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getCuitsByCuitIdPosLastVouchers
      x-operation-id-source: derived
  /cuits/{cuitId}/default-pos:
    post:
      summary: Configurar punto de venta por defecto
      description: Configura el punto de venta que se usa cuando una factura no trae ptoVta.
      tags:
      - CUITs
      parameters:
      - name: cuitId
        in: path
        description: ID del CUIT en Facturear
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - defaultPos
              properties:
                defaultPos:
                  type: integer
                  minimum: 1
      responses:
        '200':
          description: Valor por defecto actualizado
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '400':
          description: Valor inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: CUIT no encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postCuitsByCuitIdDefaultPos
      x-operation-id-source: derived
  /cuits/{cuitId}/default-invoice-type:
    post:
      summary: Configurar tipo de comprobante por defecto
      description: Configura el tipo de comprobante (código de ARCA) que se usa cuando una factura no trae invoiceType.
      tags:
      - CUITs
      parameters:
      - name: cuitId
        in: path
        description: ID del CUIT en Facturear
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - defaultInvoiceType
              properties:
                defaultInvoiceType:
                  type: integer
                  minimum: 1
      responses:
        '200':
          description: Valor por defecto actualizado
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '400':
          description: Valor inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: CUIT no encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postCuitsByCuitIdDefaultInvoiceType
      x-operation-id-source: derived
  /cuits/{cuitId}/default-concept:
    post:
      summary: Configurar concepto por defecto
      description: Configura el concepto (1 productos, 2 servicios, 3 ambos) que se usa cuando una factura no trae concepto.
      tags:
      - CUITs
      parameters:
      - name: cuitId
        in: path
        description: ID del CUIT en Facturear
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - defaultConcept
              properties:
                defaultConcept:
                  type: integer
                  minimum: 1
      responses:
        '200':
          description: Valor por defecto actualizado
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '400':
          description: Valor inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: CUIT no encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postCuitsByCuitIdDefaultConcept
      x-operation-id-source: derived
  /cuits/{cuitId}/default-iva:
    post:
      summary: Configurar alícuota de IVA por defecto
      description: Configura la alícuota de IVA (código de ARCA) preseleccionada en los formularios del dashboard.
      tags:
      - CUITs
      parameters:
      - name: cuitId
        in: path
        description: ID del CUIT en Facturear
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - defaultIva
              properties:
                defaultIva:
                  type: integer
                  minimum: 1
      responses:
        '200':
          description: Valor por defecto actualizado
          content:
            application/json:
              schema:
                type: object
                description: CUIT actualizado
        '400':
          description: Valor inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: CUIT no encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postCuitsByCuitIdDefaultIva
      x-operation-id-source: derived
  /cuits/{cuitId}/invoice-branding:
    get:
      summary: Obtener el diseño de factura
      description: Plantilla, logo, color y datos del emisor con que se imprimen las facturas del CUIT.
      tags:
      - CUITs
      parameters:
      - name: cuitId
        in: path
        description: ID del CUIT en Facturear
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Diseño de factura
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceBranding'
        '404':
          description: CUIT no encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getCuitsByCuitIdInvoiceBranding
      x-operation-id-source: derived
    put:
      summary: Cambiar el diseño de factura
      description: Cambia los campos enviados; los que no se envían quedan como están y null borra un valor. Se aplica también al PDF de las facturas ya emitidas.
      tags:
      - CUITs
      parameters:
      - name: cuitId
        in: path
        description: ID del CUIT en Facturear
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoiceBranding'
      responses:
        '200':
          description: Diseño actualizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceBranding'
        '400':
          description: Valor inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: CUIT no encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: putCuitsByCuitIdInvoiceBranding
      x-operation-id-source: derived
  /cuits/{cuitId}/email-design:
    get:
      summary: Obtener el diseño del mail
      description: El diseño del mail con el que sale la factura de este CUIT. Los campos en null usan el valor por defecto.
      tags:
      - CUITs
      parameters:
      - name: cuitId
        in: path
        description: ID del CUIT en Facturear
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Diseño del mail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailDesign'
        '404':
          description: CUIT no encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getCuitsByCuitIdEmailDesign
      x-operation-id-source: derived
    put:
      summary: Cambiar el diseño del mail
      description: Los campos que no mandás quedan como están; null (o texto vacío) vuelve al valor por defecto. En signature, el texto vacío deja el mail sin firma.
      tags:
      - CUITs
      parameters:
      - name: cuitId
        in: path
        description: ID del CUIT en Facturear
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailDesign'
      responses:
        '200':
          description: Diseño guardado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailDesign'
        '400':
          description: Valor inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: CUIT no encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: putCuitsByCuitIdEmailDesign
      x-operation-id-source: derived
components:
  schemas:
    EmailDesign:
      type: object
      description: Diseño del mail con el que sale la factura de este CUIT. null = valor por defecto
      properties:
        accentColor:
          type:
          - string
          - 'null'
          pattern: ^#[0-9a-fA-F]{6}$
          description: Color de la banda superior (#rrggbb)
        backgroundColor:
          type:
          - string
          - 'null'
          pattern: ^#[0-9a-fA-F]{6}$
          description: Color de fondo (#rrggbb)
        showLogo:
          type: boolean
          description: Mostrar el logo del CUIT en el encabezado
        subject:
          type:
          - string
          - 'null'
          maxLength: 200
          description: Asunto. Admite bloques como %emisor%
        body:
          type:
          - string
          - 'null'
          maxLength: 3000
          description: Mensaje. Admite bloques como %cliente%
        signature:
          type:
          - string
          - 'null'
          maxLength: 500
          description: Firma. null = firma por defecto; texto vacío = sin firma
    Error:
      type: object
      description: Error de la API. Los errores de autenticación (401), validación (400), CUIT inexistente (404), conflicto (409) e internos (500) vienen como application/problem+json (RFC 9457) con code, message y resolution. Otros errores vienen como JSON con error y, a veces, details y code. En los dos casos está el campo error.
      required:
      - error
      properties:
        error:
          type: string
          description: Mensaje de error
        code:
          type: string
          description: 'Código estable: unauthorized, invalid_request, cuit_not_found, conflict, internal_error, o códigos propios como SUBSCRIPTION_LIMIT_EXCEEDED'
        message:
          type: string
          description: Qué pasó (problem+json)
        resolution:
          type: string
          description: Qué hacer para resolverlo (problem+json)
        type:
          type: string
          format: uri
          description: URI del tipo de problema (problem+json)
        title:
          type: string
          description: Título corto del problema (problem+json)
        status:
          type: integer
          description: Código HTTP (problem+json)
        detail:
          type: string
          description: Igual que message (problem+json)
        details:
          description: 'Detalle del error: un texto, o la lista de errores de validación'
    Cuit:
      type: object
      description: CUIT de tu cuenta. Nunca incluye certificados, claves privadas ni tickets de acceso.
      required:
      - id
      - number
      - testing_certificate_valid
      - production_certificate_valid
      - testing_afip_connection_valid
      - production_afip_connection_valid
      - is_default
      - setupStatus
      - userId
      - createdAt
      - updatedAt
      properties:
        id:
          type: string
          example: cm1a2b3c4d5e6f7g8h9i0j
          description: ID del CUIT
        number:
          type: string
          pattern: ^[0-9]{2}-[0-9]{8}-[0-9]{1}$
          example: 20-12345678-9
          description: Número de CUIT en formato XX-XXXXXXXX-X
        persona:
          type:
          - object
          - 'null'
          description: Datos del padrón de ARCA (datosGenerales, datosMonotributo o datosRegimenGeneral, etc.) tal como los devuelve ARCA
        personaLastUpdated:
          type:
          - string
          - 'null'
          format: date-time
          description: Última actualización de los datos del padrón
        pos:
          type:
          - object
          - 'null'
          description: Puntos de venta tal como los devuelve ARCA (FEParamGetPtosVenta). La lista está en ResultGet.PtoVenta
        posLastUpdated:
          type:
          - string
          - 'null'
          format: date-time
          description: Última actualización de los puntos de venta
        default_pos:
          type:
          - integer
          - 'null'
          description: Punto de venta por defecto
          example: 1
        default_concept:
          type:
          - integer
          - 'null'
          description: Concepto por defecto (1 productos, 2 servicios, 3 productos y servicios)
          example: 2
        default_invoice_type:
          type:
          - integer
          - 'null'
          description: Tipo de comprobante por defecto (código de ARCA)
          example: 11
        default_iva:
          type:
          - integer
          - 'null'
          description: Alícuota de IVA por defecto (código de ARCA)
          example: 5
        production_certificate_expiration:
          type:
          - string
          - 'null'
          format: date-time
          description: Vencimiento del certificado de producción
        production_ta_expiration:
          type:
          - string
          - 'null'
          format: date-time
          description: Vencimiento del ticket de acceso de producción
        testing_certificate_expiration:
          type:
          - string
          - 'null'
          format: date-time
          description: Vencimiento del certificado de homologación
        testing_ta_expiration:
          type:
          - string
          - 'null'
          format: date-time
          description: Vencimiento del ticket de acceso de homologación
        testing_certificate_valid:
          type: boolean
          description: El certificado de homologación es válido
        production_certificate_valid:
          type: boolean
          description: El certificado de producción es válido
        testing_afip_connection_valid:
          type: boolean
          description: La conexión con ARCA en homologación funciona
        production_afip_connection_valid:
          type: boolean
          description: La conexión con ARCA en producción funciona
        is_default:
          type: boolean
          description: Es el CUIT por defecto de la cuenta
        setupStatus:
          type: string
          enum:
          - INITIALIZED
          - IN_PROGRESS
          - TEST_CERTIFICATE_COMPLETE
          - PROD_CERTIFICATE_COMPLETE
          - AWAITING_DELEGATION
          - DELEGATION_COMPLETE
          - AUTOMATION_IN_PROGRESS
          - AUTOMATION_FAILED
          - COMPLETED
          - SKIPPED
          description: Estado de la configuración del CUIT
        integrationMode:
          type:
          - string
          - 'null'
          enum:
          - DELEGATION
          - CERTIFICATE
          - null
          description: Modo de conexión con ARCA
        testingSetupState:
          type:
          - string
          - 'null'
          enum:
          - REQUESTED
          - COMPLETED
          - null
          description: Estado de la configuración de homologación. Solo viene en GET /cuits
        productionSetupState:
          type:
          - string
          - 'null'
          enum:
          - REQUESTED
          - COMPLETED
          - null
          description: Estado de la configuración de producción. Solo viene en GET /cuits
        userId:
          type: string
          description: ID del usuario dueño del CUIT
        createdAt:
          type: string
          format: date-time
          description: Fecha de creación
        updatedAt:
          type: string
          format: date-time
          description: Fecha de última actualización
    LastVoucher:
      type: object
      properties:
        ptoVta:
          type: integer
          description: Punto de venta
        invoiceType:
          type: integer
          description: Código de ARCA del tipo de comprobante
        voucherNumber:
          type: integer
          description: Último número autorizado
        date:
          type:
          - string
          - 'null'
          description: Fecha del comprobante en ARCA (AAAA-MM-DD)
        invoiceId:
          type:
          - string
          - 'null'
          description: ID de la factura en Facturear, si se emitió desde Facturear
    PointsOfSale:
      type: object
      properties:
        pos:
          type:
          - object
          - 'null'
          properties:
            pos:
              description: Respuesta de ARCA a FEParamGetPtosVenta guardada (ResultGet.PtoVenta con Nro, EmisionTipo, Bloqueado y FchBaja)
            posLastUpdated:
              type:
              - string
              - 'null'
              format: date-time
              description: Última vez que se consultaron los puntos de venta en ARCA
            default_pos:
              type:
              - integer
              - 'null'
              description: Punto de venta por defecto
        lastInvoices:
          type: array
          description: La última factura autorizada desde Facturear en cada punto de venta, en el entorno de la API key
          items:
            type: object
            properties:
              ptoVta:
                type: integer
              id:
                type: string
                description: ID de la factura
              invoiceType:
                type:
                - integer
                - 'null'
              voucherNumber:
                type: integer
              createdAt:
                type: string
                format: date-time
    InvoiceBranding:
      type: object
      properties:
        template:
          type: string
          enum:
          - clasico
          - moderno
          - minimalista
          - elegante
          description: Plantilla visual. Por defecto clasico
        paperSize:
          type: string
          enum:
          - A4
          - LETTER
          - LEGAL
          description: 'Tipo de hoja: A4 (por defecto), carta u oficio'
        accentColor:
          type:
          - string
          - 'null'
          pattern: ^#[0-9a-fA-F]{6}$
          description: 'Color de acento #rrggbb. null usa el de la plantilla'
        logo:
          type:
          - string
          - 'null'
          description: Logo como data URL (data:image/png|jpeg|webp;base64,...), hasta 512 KB
        tradeName:
          type:
          - string
          - 'null'
          maxLength: 120
          description: Nombre de fantasía
        activityStart:
          type:
          - string
          - 'null'
          format: date
          description: Fecha de inicio de actividades (AAAA-MM-DD)
        address:
          type:
          - string
          - 'null'
          maxLength: 200
          description: Domicilio comercial, si difiere del domicilio fiscal del padrón
        footerNote:
          type:
          - string
          - 'null'
          maxLength: 500
          description: Texto libre al pie de la factura
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: 'API Key para autenticación. Formato: test_sk_xxx para testing, prod_sk_xxx para producción.'