Consultar Solicitações

Os endpoints abaixo permitem consultar solicitações de PL/Cota enviadas via API e recuperar recibos.

Regras de Acesso

Usuário sysadmin pode consultar solicitações e baixar recibos. Para usuários de instituição, são exigidas as regras abaixo:

Regra	Valor esperado
Perfil	supervisor ou operator
Papel	Administrador, Gestor ou Controladoria
Serviço	PLCOTA
Funcionalidade	PL_COTA_ENVIO

Usuários de instituição consultam apenas os recibos associados à própria instituição.

Consulta Paginada

• Método: GET
• Caminho: /api/v1/pl-cota/solicitacoes

Headers

Header	Valor	Obrigatório	Descrição
Authorization	Bearer <token>	Sim	Token de autenticação JWT
X-Correlation-ID	<uuid>	Não	ID para rastreabilidade

Query Params

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
page	Number	Não	1	Página desejada. Inicia em 1
pageSize	Number	Não	10	Quantidade de itens por página. Máximo 500
codigoRecibo	String	Não	-	Código do recibo com 15 caracteres
tipo	String	Não	-	Tipo da consulta. Valor aceito: ARQUIVOS

Exemplo cURL

curl -G "https://<host>/api/v1/pl-cota/solicitacoes" \
  -H "Authorization: Bearer <seu_token>" \
  --data-urlencode "page=1" \
  --data-urlencode "pageSize=10" \
  --data-urlencode "tipo=ARQUIVOS" \
  --data-urlencode "codigoRecibo=XPUJFQOZXVMK2KQ"

Resposta - 200 OK

{
  "data": [
    {
      "codigoRecibo": "XPUJFQOZXVMK2KQ",
      "statusProcessamento": "3",
      "dataHoraEnvio": "12/03/2026 10:15:30",
      "dataHoraProcessamento": "12/03/2026 10:16:05",
      "totalInformEnviadas": 2,
      "nomeArquivo": "plcota_lote_001.csv",
      "usuario": "usuario@empresa.com.br",
      "cnpjUsuario": "11222333000199",
      "totalInformComSucesso": 1,
      "totalInformParaRevisar": 0,
      "totalInformComErro": 1,
      "informes": [
        {
          "tipoIdentificador": "2",
          "idRegistro": "FUNDOABC123",
          "dataInformacao": "2026-03-12",
          "tipoInforme": "1",
          "moeda": "BRL",
          "valorCota": "1.23456789",
          "valorPatrimLiq": "1000000.00000",
          "codigoAnbima": "FUNDOABC123",
          "nomeComercial": "Fundo Exemplo",
          "cnpjOuIdSubclasse": "-",
          "statusEnvio": "2",
          "inconsistencias": [
            {
              "codigoErro": "001",
              "mensagemErro": "Campo obrigatório não informado",
              "campoErro": "valorCota",
              "valorErro": ""
            }
          ]
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 10,
    "totalItems": 1,
    "totalPages": 1
  },
  "message": "Solicitações encontradas com sucesso",
  "type": "success"
}

Download de Recibo CSV

• Método: GET
• Caminho: /api/v1/pl-cota/solicitacoes/{codigoRecibo}/recibo

Exemplo cURL

curl -X GET "https://<host>/api/v1/pl-cota/solicitacoes/XPUJFQOZXVMK2KQ/recibo" \
  -H "Authorization: Bearer <seu_token>"

O retorno é um arquivo CSV com o recibo da solicitação.

Consulta de Recibos por Critério

• Método: POST
• Caminho: /api/v1/pl-cota/solicitacoes/recibo

Este endpoint permite consultar recibos por lista de recibos e/ou intervalo de data/hora de envio.

Corpo da Requisição

{
  "recibo": [
    "QOGUEZ7OLAZS2VA"
  ],
  "dtInicEnvio": "20240101T090000",
  "dtFinEnvio": "20240131T180000"
}

Campo	Tipo	Obrigatório	Descrição
recibo	Array de String	Não	Lista de códigos de recibo. Máximo 20
dtInicEnvio	String	Não	Data/hora inicial no formato aaaammddThhmmss
dtFinEnvio	String	Não	Data/hora final no formato aaaammddThhmmss

Resposta - 200 OK

[
  {
    "recibo": "QOGUEZ7OLAZS2VA",
    "idRequest": "b4b8f3fd-86c2-49b0-a8a5-0f5b4a6cb700",
    "instituicao": "11222333000199",
    "usuario": "usuario@empresa.com.br",
    "dataHoraEnvio": "20240101T090000",
    "dataHoraProc": "20240101T090030",
    "totalInformacoes": 1,
    "statusProc": "Processado com sucesso",
    "informacoes": [
      {
        "sequential": 1,
        "tipoIdentificador": "Codigo_STI",
        "idRegistro": "CODIGO123",
        "tipoInforme": "PL_Cota",
        "moeda": "BRL",
        "dataInformacao": "20240101",
        "statusEnvio": "OK",
        "msgErro": []
      }
    ]
  }
]

Campos de Status

statusProcessamento

Código	Descrição
1	Pendente
2	Em processamento
3	Processado com sucesso
4	Processado com erro
5	Leiaute inválido

statusEnvio

Código	Descrição
0	Pendente
1	Recebido
2	Rejeitado

Na consulta de recibos por critério, o detalhe das informações retorna statusEnvio como OK ou NOK.

Erros

Erro de Validação - 400 Bad Request

Exemplo: codigoRecibo fora do tamanho esperado.

{
  "data": "",
  "message": "O codigo recibo deve ter 15 caracteres",
  "type": "error"
}

Sem Autenticação - 401 Unauthorized

Retornado quando o token não é enviado ou é inválido.

Sem Permissão - 403 Forbidden

Retornado quando o token é válido, mas não atende às regras de perfil, papel, serviço ou funcionalidade do PL/Cota.