openapi: 3.0.3
info:
  title: Giro.Tech - Importação de Faturas para Antecipação
  version: 1.0.0
  description: API para envio de faturas que podem ser antecipadas por fornecedores.
servers:
  - url: 'https://api.integration.giro.tech'
    description: Ambiente de Produção
  - url: 'https://staging.integration.giro.tech'
    description: Ambiente de Homologação
paths:
  /api/anticipations/titles:
    post:
      summary: Importar faturas para antecipação
      description: Envia uma lista de até 100 faturas para que sejam ofertadas aos fornecedores para antecipação.
      operationId: importAnticipationTitles
      tags:
        - Antecipações
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                titles:
                  type: array
                  description: Lista de faturas a serem importadas.
                  maxItems: 100
                  minItems: 1
                  items:
                    type: object
                    properties:
                      buyer:
                        description: Informações do Sacado (empresa que pagará a fatura).
                        type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - INDIVIDUAL
                              - CORPORATION
                            description: |
                              Tipo de pessoa (INDIVIDUAL para Pessoa Física, CORPORATION para Pessoa Jurídica).
                          identificationNumber:
                            type: string
                            description: |
                              Número de identificação (CPF para INDIVIDUAL, CNPJ para CORPORATION).
                          name:
                            type: string
                            description: Nome completo ou Razão Social.
                        required:
                          - type
                          - identificationNumber
                          - name
                      provider:
                        description: Informações do Fornecedor (empresa que receberá o valor da fatura).
                        allOf:
                          - type: object
                            description: Representa uma parte envolvida (Sacado ou Fornecedor).
                            properties:
                              type:
                                type: string
                                enum:
                                  - INDIVIDUAL
                                  - CORPORATION
                                description: |
                                  Tipo de pessoa (INDIVIDUAL para Pessoa Física, CORPORATION para Pessoa Jurídica).
                              identificationNumber:
                                type: string
                                description: |
                                  Número de identificação (CPF para INDIVIDUAL, CNPJ para CORPORATION).
                              name:
                                type: string
                                description: Nome completo ou Razão Social.
                            required:
                              - type
                              - identificationNumber
                              - name
                          - type: object
                            description: Detalhes específicos do Fornecedor.
                            properties:
                              email:
                                type: string
                                format: email
                                description: Endereço de e-mail do fornecedor para notificações.
                              phone:
                                type: string
                                description: Número de telefone do fornecedor.
                              externalId:
                                type: string
                                description: Identificador único do fornecedor no sistema de origem.
                              canAnticipate:
                                type: boolean
                                description: Indica se o fornecedor está habilitado para antecipar faturas.
                            required:
                              - externalId
                              - canAnticipate
                      order:
                        description: Detalhes da fatura/título.
                        type: object
                        properties:
                          uid:
                            type: string
                            description: Identificador único da fatura no sistema de origem.
                          nfNumber:
                            type: string
                            description: Número da Nota Fiscal.
                          nfSerie:
                            type: string
                            description: Série da Nota Fiscal.
                          amount:
                            type: integer
                            description: |
                              Valor total da fatura em centavos (ex: 10000 para R$ 100,00).
                              Considerar usar 'number' com 'format: double' ou string para valores monetários precisos, ou integer representando centavos.
                            example: 10000
                          orderDetail:
                            type: string
                            description: Descrição ou detalhes adicionais da fatura/pedido.
                          createdDate:
                            type: string
                            format: date
                            description: Data de criação/emissão da fatura (YYYY-MM-DD).
                            example: '2024-01-20'
                          entryDate:
                            type: string
                            format: date
                            description: Data de entrada da fatura no sistema (YYYY-MM-DD).
                            example: '2024-01-21'
                          dueDate:
                            type: string
                            format: date
                            description: Data de vencimento da fatura (YYYY-MM-DD).
                            example: '2024-02-20'
                          invoiceKey:
                            type: string
                            description: 'Chave da Nota Fiscal Eletrônica (NF-e), se aplicável.'
                          installmentNumber:
                            type: string
                            description: 'Número da parcela, se a fatura for parte de um parcelamento.'
                        required:
                          - uid
                          - amount
                          - createdDate
                          - dueDate
                    required:
                      - buyer
                      - provider
                      - order
              required:
                - titles
      responses:
        '200':
          description: Faturas importadas com sucesso.
        '400':
          description: |-
            Erro de negócio ou validação. Exemplos:
            - Formato de dados inválido.
            - Fornecedor não habilitado para antecipação.
            - Limite de faturas excedido.
            - CNPJ/CPF inválido.
          content:
            application/json:
              schema:
                type: object
                description: Schema padrão para respostas de erro.
                properties:
                  timestamp:
                    type: string
                    format: date-time
                    description: Data e hora da ocorrência do erro.
                  status:
                    type: integer
                    description: Código de status HTTP.
                  error:
                    type: string
                    description: 'Categoria do erro (ex "Bad Request", "Internal Server Error").'
                  message:
                    type: string
                    description: Mensagem detalhada do erro.
                  path:
                    type: string
                    description: Caminho da requisição que originou o erro.
                required:
                  - timestamp
                  - status
                  - error
                  - message
                  - path
        '401':
          description: Não autorizado. Token JWT inválido ou ausente.
          content:
            application/json:
              schema:
                type: object
                description: Schema padrão para respostas de erro.
                properties:
                  timestamp:
                    type: string
                    format: date-time
                    description: Data e hora da ocorrência do erro.
                  status:
                    type: integer
                    description: Código de status HTTP.
                  error:
                    type: string
                    description: 'Categoria do erro (ex "Bad Request", "Internal Server Error").'
                  message:
                    type: string
                    description: Mensagem detalhada do erro.
                  path:
                    type: string
                    description: Caminho da requisição que originou o erro.
                required:
                  - timestamp
                  - status
                  - error
                  - message
                  - path
        '500':
          description: Erro interno no servidor. Tente novamente mais tarde.
          content:
            application/json:
              schema:
                type: object
                description: Schema padrão para respostas de erro.
                properties:
                  timestamp:
                    type: string
                    format: date-time
                    description: Data e hora da ocorrência do erro.
                  status:
                    type: integer
                    description: Código de status HTTP.
                  error:
                    type: string
                    description: 'Categoria do erro (ex "Bad Request", "Internal Server Error").'
                  message:
                    type: string
                    description: Mensagem detalhada do erro.
                  path:
                    type: string
                    description: Caminho da requisição que originou o erro.
                required:
                  - timestamp
                  - status
                  - error
                  - message
                  - path
      security:
        - bearerAuth: []
  /api/anticipations/conciliation:
    get:
      summary: Consultar conciliação de antecipações
      description: 'Consulta operações de antecipação realizadas, para conciliação financeira no ERP do Sacado.'
      operationId: getAnticipationConciliation
      tags:
        - Antecipações
      parameters:
        - name: anticipationDate
          in: query
          description: |-
            Filtra títulos antecipados com data de aceite (`acceptedDate`) maior ou igual à informada.
            Formato: YYYY-MM-DD.
          required: false
          schema:
            type: string
            format: date
        - name: conciliationDate
          in: query
          description: |-
            Filtra títulos antecipados com data de aceite (`acceptedDate`) igual à informada.
            Formato: YYYY-MM-DD.
          required: false
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Consulta de conciliação retornada com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  titles:
                    type: array
                    description: Lista de títulos antecipados para conciliação.
                    items:
                      type: object
                      description: Detalhes de um título antecipado para conciliação.
                      properties:
                        order:
                          type: object
                          properties:
                            uid:
                              type: string
                              description: Identificador único da fatura original.
                          required:
                            - uid
                        financialAgent:
                          description: Agente Financeiro responsável pelo pagamento.
                          allOf:
                            - type: object
                              description: Representa uma parte envolvida (Sacado ou Fornecedor).
                              properties:
                                type:
                                  type: string
                                  enum:
                                    - INDIVIDUAL
                                    - CORPORATION
                                  description: |
                                    Tipo de pessoa (INDIVIDUAL para Pessoa Física, CORPORATION para Pessoa Jurídica).
                                identificationNumber:
                                  type: string
                                  description: |
                                    Número de identificação (CPF para INDIVIDUAL, CNPJ para CORPORATION).
                                name:
                                  type: string
                                  description: Nome completo ou Razão Social.
                              required:
                                - type
                                - identificationNumber
                                - name
                            - type: object
                              description: Detalhes do Agente Financeiro que realiza o pagamento da antecipação.
                              properties:
                                buyerIsFinancial:
                                  type: boolean
                                  description: Indica se o próprio sacado é o agente financeiro.
                                payment:
                                  description: Detalhes do pagamento realizado pelo agente financeiro.
                                  type: object
                                  properties:
                                    type:
                                      type: string
                                      enum:
                                        - BANK_TRANSFER
                                        - BOLETO
                                      description: Forma de pagamento.
                                    bank:
                                      type: string
                                      description: Código ou nome do banco para transferência.
                                    agency:
                                      type: string
                                      description: Número da agência bancária para transferência.
                                    agencyDigit:
                                      type: string
                                      description: 'Dígito verificador da agência, se houver.'
                                    account:
                                      type: string
                                      description: Número da conta bancária para transferência.
                                    accountDigit:
                                      type: string
                                      description: 'Dígito verificador da conta, se houver.'
                        buyerIdentification:
                          type: string
                          description: Identificação (CPF/CNPJ) do Sacado.
                        providerExternalId:
                          type: string
                          description: Identificador externo do Fornecedor.
                        platformDiscountedValue:
                          type: number
                          format: double
                          description: Valor descontado pela plataforma (taxas da Giro.Tech).
                        financialDiscountedValue:
                          type: number
                          format: double
                          description: 'Valor descontado pelo agente financeiro (juros, taxas do financiador).'
                        buyerDiscountedValue:
                          type: number
                          format: double
                          description: 'Valor descontado pelo sacado (descontos comerciais, etc.).'
                        billingFee:
                          type: number
                          format: double
                          description: |
                            Taxa de cobrança (ex: emissão de boleto).
                        moneyTransferFee:
                          type: number
                          format: double
                          description: |
                            Taxa de transferência (TED/DOC).
                        originalValue:
                          type: number
                          format: double
                          description: |
                            Valor original da fatura.
                        anticipatedDueDate:
                          type: string
                          format: date
                          description: Data efetiva da antecipação.
                        acceptedDate:
                          type: string
                          format: date
                          description: Data em que a antecipação foi aceita/confirmada.
                        platformCommission:
                          type: string
                          description: |
                            Comissão da plataforma sobre a operação.
                        provider:
                          type: object
                          description: Detalhes do fornecedor para conciliação.
                          properties:
                            identification:
                              type: string
                              description: Identificação (CPF/CNPJ) do Fornecedor.
                            externalId:
                              type: string
                              description: Identificador externo do Fornecedor.
                            bankAccount:
                              description: Conta bancária do fornecedor para crédito.
                              type: object
                              properties:
                                bank:
                                  type: string
                                  description: Código ou nome do banco.
                                agency:
                                  type: string
                                  description: Número da agência bancária.
                                agencyDigit:
                                  type: string
                                  description: 'Dígito verificador da agência, se houver.'
                                account:
                                  type: string
                                  description: Número da conta bancária.
                                accountDigit:
                                  type: string
                                  description: 'Dígito verificador da conta, se houver.'
                              required:
                                - bank
                                - agency
                                - account
                      required:
                        - order
                        - financialAgent
                        - buyerIdentification
                        - providerExternalId
                        - originalValue
                        - anticipatedDueDate
                        - acceptedDate
        '400':
          description: Erro de validação nos parâmetros da consulta.
          content:
            application/json:
              schema:
                type: object
                description: Schema padrão para respostas de erro.
                properties:
                  timestamp:
                    type: string
                    format: date-time
                    description: Data e hora da ocorrência do erro.
                  status:
                    type: integer
                    description: Código de status HTTP.
                  error:
                    type: string
                    description: 'Categoria do erro (ex "Bad Request", "Internal Server Error").'
                  message:
                    type: string
                    description: Mensagem detalhada do erro.
                  path:
                    type: string
                    description: Caminho da requisição que originou o erro.
                required:
                  - timestamp
                  - status
                  - error
                  - message
                  - path
        '401':
          description: Não autorizado. Token JWT inválido ou ausente.
          content:
            application/json:
              schema:
                type: object
                description: Schema padrão para respostas de erro.
                properties:
                  timestamp:
                    type: string
                    format: date-time
                    description: Data e hora da ocorrência do erro.
                  status:
                    type: integer
                    description: Código de status HTTP.
                  error:
                    type: string
                    description: 'Categoria do erro (ex "Bad Request", "Internal Server Error").'
                  message:
                    type: string
                    description: Mensagem detalhada do erro.
                  path:
                    type: string
                    description: Caminho da requisição que originou o erro.
                required:
                  - timestamp
                  - status
                  - error
                  - message
                  - path
        '500':
          description: Erro interno no servidor.
          content:
            application/json:
              schema:
                type: object
                description: Schema padrão para respostas de erro.
                properties:
                  timestamp:
                    type: string
                    format: date-time
                    description: Data e hora da ocorrência do erro.
                  status:
                    type: integer
                    description: Código de status HTTP.
                  error:
                    type: string
                    description: 'Categoria do erro (ex "Bad Request", "Internal Server Error").'
                  message:
                    type: string
                    description: Mensagem detalhada do erro.
                  path:
                    type: string
                    description: Caminho da requisição que originou o erro.
                required:
                  - timestamp
                  - status
                  - error
                  - message
                  - path
      security:
        - bearerAuth: []
  /api/providers:
    post:
      summary: Importar fornecedores
      description: Envia uma lista de até 100 fornecedores para cadastro ou atualização na plataforma Giro.Tech.
      operationId: importProviders
      tags:
        - Fornecedores
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                providers:
                  type: array
                  description: Lista de fornecedores a serem importados.
                  maxItems: 100
                  minItems: 1
                  items:
                    type: object
                    description: Dados para importação (cadastro ou atualização) de um fornecedor.
                    properties:
                      type:
                        type: string
                        enum:
                          - INDIVIDUAL
                          - CORPORATION
                        description: |
                          Tipo de pessoa (INDIVIDUAL para Pessoa Física, CORPORATION para Pessoa Jurídica).
                      identificationNumber:
                        type: string
                        description: |
                          Número de identificação (CPF para INDIVIDUAL, CNPJ para CORPORATION).
                      name:
                        type: string
                        description: Nome completo ou Razão Social.
                      externalId:
                        type: string
                        description: Identificador único do fornecedor no sistema de origem do cliente.
                      canAnticipate:
                        type: boolean
                        description: Indica se o fornecedor está habilitado para antecipar faturas.
                        default: true
                      phones:
                        type: array
                        description: Lista de telefones do fornecedor.
                        items:
                          type: object
                          description: Telefone do fornecedor.
                          properties:
                            number:
                              type: string
                              description: Número do telefone com DDD.
                              example: '11999998888'
                          required:
                            - number
                        maxItems: 5
                      emailAddresses:
                        type: array
                        description: Lista de endereços de e-mail do fornecedor.
                        items:
                          type: object
                          description: Endereço de e-mail do fornecedor.
                          properties:
                            email:
                              type: string
                              format: email
                              description: Endereço de e-mail.
                          required:
                            - email
                        maxItems: 5
                      accounts:
                        type: array
                        description: Lista de contas bancárias do fornecedor.
                        items:
                          type: object
                          description: Conta bancária do fornecedor para recebimento.
                          properties:
                            bankNumber:
                              type: string
                              description: Código do banco (COMPE).
                              example: '001'
                            agencyNumber:
                              type: string
                              description: Número da agência.
                              example: '1234'
                            accountNumber:
                              type: string
                              description: Número da conta.
                              example: '56789'
                            accountDigit:
                              type: string
                              description: Dígito verificador da conta.
                              example: '0'
                            type:
                              type: string
                              enum:
                                - CHECKING_ACCOUNT
                                - SAVINGS_ACCOUNT
                              description: 'Tipo da conta (CHECKING_ACCOUNT para Conta Corrente, SAVINGS_ACCOUNT para Conta Poupança).'
                            defaultAccount:
                              type: boolean
                              description: Indica se esta é a conta padrão para crédito.
                              default: false
                          required:
                            - bankNumber
                            - agencyNumber
                            - accountNumber
                            - type
                        maxItems: 3
                    required:
                      - type
                      - identificationNumber
                      - name
                      - externalId
                      - canAnticipate
              required:
                - providers
      responses:
        '200':
          description: |-
            Fornecedores importados/atualizados com sucesso.
            A resposta pode incluir um resumo do processamento ou status individual (a ser definido).
        '400':
          description: |-
            Erro de negócio ou validação nos dados dos fornecedores. Exemplos:
            - Formato de dados inválido para um ou mais fornecedores.
            - CPF/CNPJ inválido ou já existente com `externalId` diferente.
            - Limite de itens excedido.
          content:
            application/json:
              schema:
                type: object
                description: Schema padrão para respostas de erro.
                properties:
                  timestamp:
                    type: string
                    format: date-time
                    description: Data e hora da ocorrência do erro.
                  status:
                    type: integer
                    description: Código de status HTTP.
                  error:
                    type: string
                    description: 'Categoria do erro (ex "Bad Request", "Internal Server Error").'
                  message:
                    type: string
                    description: Mensagem detalhada do erro.
                  path:
                    type: string
                    description: Caminho da requisição que originou o erro.
                required:
                  - timestamp
                  - status
                  - error
                  - message
                  - path
        '401':
          description: Não autorizado. Token JWT inválido ou ausente.
          content:
            application/json:
              schema:
                type: object
                description: Schema padrão para respostas de erro.
                properties:
                  timestamp:
                    type: string
                    format: date-time
                    description: Data e hora da ocorrência do erro.
                  status:
                    type: integer
                    description: Código de status HTTP.
                  error:
                    type: string
                    description: 'Categoria do erro (ex "Bad Request", "Internal Server Error").'
                  message:
                    type: string
                    description: Mensagem detalhada do erro.
                  path:
                    type: string
                    description: Caminho da requisição que originou o erro.
                required:
                  - timestamp
                  - status
                  - error
                  - message
                  - path
        '500':
          description: Erro interno no servidor. Tente novamente mais tarde.
          content:
            application/json:
              schema:
                type: object
                description: Schema padrão para respostas de erro.
                properties:
                  timestamp:
                    type: string
                    format: date-time
                    description: Data e hora da ocorrência do erro.
                  status:
                    type: integer
                    description: Código de status HTTP.
                  error:
                    type: string
                    description: 'Categoria do erro (ex "Bad Request", "Internal Server Error").'
                  message:
                    type: string
                    description: Mensagem detalhada do erro.
                  path:
                    type: string
                    description: Caminho da requisição que originou o erro.
                required:
                  - timestamp
                  - status
                  - error
                  - message
                  - path
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        Autenticação via token JWT no cabeçalho 'Authorization: <token>'. 
