Antecipação de Fornecedores (GTFor)

Giro.Tech - Importação de Faturas para Antecipação API

API para envio de faturas que podem ser antecipadas por fornecedores e para gerenciamento de fornecedores na plataforma Giro.Tech, seguindo o padrão de especificação OpenAPI.

Estrutura OpenAPI

A especificação OpenAPI está organizada da seguinte forma:

openapi-gtfor/
├── gtfor-openapi-v1.yml        # Arquivo principal com paths e security
├── components/
│   ├── common-schemas.yml    # Todos os schemas em um único arquivo
│   └── securitySchemes.yml   # Configurações de segurança (Bearer JWT)
└── paths/
    ├── anticipations.yml     # Endpoints de antecipação de faturas
    └── providers.yml         # Endpoints de gerenciamento de fornecedores

Endpoints

1. Importar Faturas para Antecipação

   • POST /api/anticipations/titles

   • Envia uma lista de faturas (títulos) para serem ofertadas aos fornecedores.

   • Permite o envio de até 100 faturas por requisição.

2. Consultar Conciliação de Antecipações

   • GET /api/anticipations/conciliation

   • Consulta operações de antecipação realizadas para fins de conciliação financeira.

   • Permite filtrar por anticipationDate (data de aceite maior ou igual) ou conciliationDate (data de aceite igual).

3. Importar Fornecedores

   • POST /api/providers

   • Envia uma lista de fornecedores para cadastro ou atualização na plataforma.

   • Permite o envio de até 100 fornecedores por requisição.

Schemas Principais

Todos os schemas estão definidos em components/common-schemas.yml:

1. Party

   • Representa uma parte envolvida (Sacado ou Fornecedor base).

   • Contém tipo (Pessoa Física/Jurídica), número de identificação (CPF/CNPJ) e nome/razão social.

2. Provider (usado em Antecipações)

   • Detalhes específicos do Fornecedor para o contexto de antecipação, estendendo Party.

   • Inclui e-mail, telefone, ID externo e indicação se pode antecipar.

3. Order

   • Representa uma fatura (título) a ser antecipada (usado na importação de faturas).

   • Contém UID, número/série da NF, valor (em centavos), datas (criação, entrada, vencimento), chave da NF-e e número da parcela.

4. ProviderImport

   • Dados para importação (cadastro ou atualização) de um fornecedor.

   • Inclui dados básicos (tipo, identificação, nome, ID externo, flag canAnticipate), além de listas de telefones, e-mails e contas bancárias.

5. ProviderPhone, ProviderEmail, ProviderAccount

   • Sub-schemas detalhando as informações de contato e bancárias para ProviderImport.

6. ConciliationTitle

   • Detalhes de um título antecipado retornado na consulta de conciliação.

   • Inclui UID da fatura original, informações do agente financeiro, identificações do sacado e fornecedor, valores descontados (plataforma, financeiro, sacado), taxas, valor original, datas de aceite/antecipação e comissão.

7. FinancialAgent

   • Informações sobre o Agente Financeiro, estendendo Party.

   • Inclui se o sacado é o próprio agente e detalhes do pagamento.

8. Payment

   • Detalhes do pagamento ao agente financeiro (tipo, dados bancários para transferência).

9. BankAccount

   • Detalhes de uma conta bancária (banco, agência, conta).

10. ErrorResponse

    • Schema padrão para respostas de erro da API.

    • Inclui timestamp, status HTTP, categoria do erro, mensagem detalhada e caminho da requisição.