Extração de estoque (WIP)

POST /v1/inventory-exports · header iorq-fund-id · resultado por e-mail

🚧

Em estágio inicial (WIP)

Esta rota é a primeira versão da extração de estoque. O contrato da rota, as colunas do arquivo e os limites abaixo ainda estão em revisão e podem mudar sem nova versão da API. Antes de automatizar algo em cima do arquivo, fale com o seu contato na IORQ.

1. O que esta rota faz

Ela pede o estoque do fundo: a lista das parcelas do fundo, com os dados da operação, do devedor e dos valores. A geração é assíncrona:

1. a chamada responde 202 com um export_id assim que o pedido é aceito;
2. a IORQ gera o arquivo CSV em seguida;
3. o link de download chega no e-mail cadastrado da credencial, válido por 12 horas.

O arquivo não vem na resposta da chamada, e não há rota para consultar o pedido pelo export_id. O resultado chega só por e-mail.

2. Quem pode pedir

• A permissão é própria e vale por fundo. A credencial precisa da permissão de extração de estoque no fundo do header. A IORQ concede essa permissão fundo a fundo, a pedido.
• Ela é independente da permissão de leitura. A permissão de leitura de covenants e indicadores não abre esta rota, e a de estoque não abre as rotas de leitura.
• Vale para os dois perfis. Uma credencial de originador que também é cotista do fundo pode receber esta permissão, além da credencial de investidor. Ver Perfis de acesso.
• O link vai para o e-mail cadastrado na credencial. É o endereço informado à IORQ quando a credencial foi criada. Para trocá-lo, fale com o seu contato na IORQ. O arquivo leva CPF/CNPJ e nome de devedor: confira que esse endereço é de quem deve receber o estoque.

3. Fluxo

sequenceDiagram
    participant CLI as Cliente
    participant AUTH as IORQ Auth (Cognito)
    participant API as API do investidor
    participant IORQ as IORQ (geração)
    participant MAIL as E-mail cadastrado

    CLI->>AUTH: POST /oauth2/token (client_id + client_secret)
    AUTH-->>CLI: access_token (JWT, exp=1h)
    CLI->>API: POST /v1/inventory-exports (Bearer + iorq-fund-id)
    API-->>CLI: 202 { export_id }
    API->>IORQ: pedido enfileirado
    IORQ->>IORQ: gera o CSV do estoque do fundo
    IORQ->>MAIL: e-mail com o link de download (12 h)
    MAIL->>IORQ: download do CSV pelo link

4. O pedido

curl -X POST 'https://investor-api.iorq.com.br/v1/inventory-exports' \
  -H 'Authorization: Bearer eyJraWQiOiJyc2EtMjAyNiIs...' \
  -H 'iorq-fund-id: 6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f'

Sem corpo. O fundo vai só no header iorq-fund-id, com o id do fundo.

{
  "export_id": "2fe09d49-b6f3-4361-9060-5b83587b740e"
}

Guarde o export_id: é ele que a IORQ usa para localizar o pedido quando um estoque não chega.

5. O arquivo

• Formato: CSV em UTF-8 com BOM, separador ;, quebra de linha CRLF. Números com vírgula decimal e sem separador de milhar; datas no formato ISO (aaaa-mm-dd); campo sem valor sai vazio. Um texto que começaria uma fórmula numa planilha (=, +, -, @) sai com ' na frente.
• Granularidade: uma linha por parcela.
• Sem filtro de estado: entram parcelas em qualquer estado, inclusive as já liquidadas. Isso permite conciliar uma parcela que já foi baixada na IORQ e ainda aparece de pé na administradora.
• É uma foto do instante da geração, não uma posição numa data-base. Dois pedidos em momentos diferentes podem trazer valores e estados diferentes.
• É a visão da gestora (IORQ), não a da administradora do fundo. As duas podem divergir enquanto um evento ainda não foi refletido na administradora.

🚧

Colunas em revisão

A lista acima é a primeira versão. Colunas podem entrar, sair ou mudar de nome. Não dependa da posição de uma coluna: leia pelo nome do cabeçalho.

6. Pedidos repetidos

Um novo pedido da mesma credencial para o mesmo fundo em até 15 minutos do anterior também responde 202, com um export_id novo, mas não gera um segundo arquivo nem um segundo e-mail: o e-mail que chega é o do primeiro pedido. Depois de 15 minutos, um pedido novo gera um arquivo novo.

Credenciais diferentes no mesmo fundo, e a mesma credencial em fundos diferentes, não se bloqueiam.

7. Limites desta primeira versão

• Falha silenciosa. Se a geração falhar, hoje nenhum e-mail é enviado: nem o link, nem um aviso. Se o e-mail não chegar em alguns minutos, peça de novo; se continuar sem chegar, informe o export_id ao seu contato na IORQ.
• Sem consulta de status. Não há rota para saber se um pedido terminou nem para baixar o arquivo pelo export_id.
• Link de 12 horas. Depois disso o link expira; peça o estoque de novo.
• Fundos muito grandes. A geração tem um tempo máximo. Num fundo com volume muito alto de parcelas ela pode não terminar, e então nenhum e-mail chega.
• Só por e-mail. O arquivo não é entregue por webhook nem pela resposta da chamada.

8. Erros

O formato dos erros é o mesmo das demais rotas da API do investidor (Erros). Os específicos desta rota:

Em todo erro acima, nada é enfileirado e nenhum e-mail é enviado.