Fluxos de negócio

Os endpoints da API são organizados por domínio, mas o uso real costuma seguir fluxos de negócio. Abaixo estão as sequências recomendadas para orientar integrações.

Acesso e contexto da empresa

1. POST /api/auth/v1/token
2. GET /api/auth/v1/current-user
3. GET /api/company/v1/get-user-companies
4. GET /api/company/v1/{company_role_id}

Use esse fluxo para montar a sessão do usuário e selecionar a empresa/papel antes de qualquer operação.

Cadastro e documentação de empresa

1. Consultar empresa: GET /api/company/v1/{company_role_id}
2. Listar documentos: GET /api/company/v1/{company_role_id}/documents
3. Enviar documento: POST /api/company/v1/{company_role_id}/documents
4. Confirmar upload: POST /api/company/v1/{company_role_id}/documents/confirm-upload
5. Validar extração: POST /api/company/v1/{company_role_id}/document-extraction/{extraction_id}/validate

Esse fluxo cobre onboarding, complementação cadastral e validação documental.

Cotação de recebíveis

1. Listar compradores conhecidos: GET /api/v1/quotation/{company_role_id}/buyers
2. Criar cotação: POST /api/v1/quotation/{company_role_id}/new
3. Importar nota/XML/PDF: POST /api/v1/quotation/{quotation_id}/import ou POST /api/v1/quotation/{quotation_id}/import-pdf
4. Consultar dados gerais: GET /api/v1/quotation/{quotation_id}/general-data
5. Ajustar documentação: PATCH /api/v1/quotation/{quotation_id}/documentation

Use a referência da API para ver os parâmetros exigidos em cada etapa.

Marketplace, lances e títulos

1. Listar produtos: GET /api/v1/marketplace/products
2. Listar títulos: POST /api/v1/marketplace/{company_role_id}
3. Consultar título: GET /api/v1/marketplace/{company_role_id}/title/{title_id}
4. Criar lance: POST /api/v1/marketplace/{company_role_id}/title/{title_id}/bid
5. Consultar lance: GET /api/v1/marketplace/{company_role_id}/bid/{bid_id}
6. Confirmar pagamento, quando aplicável: POST /api/v1/marketplace/{company_role_id}/title/{title_id}/confirm-payment

Esse é o fluxo central para financiadores e operações de compra de recebíveis.

Conta escrow e relatórios

1. Listar contas: GET /api/escrow-account/v1/{company_role_id}
2. Consultar extrato: GET /api/escrow-account/v1/{company_role_id}/accounts/{account_id}/extract
3. Listar statements: GET /api/escrow-account/v1/{company_role_id}/accounts/{account_id}/statements
4. Consultar relatórios: GET /api/reports/v1/{company_role_id}/seller-summary, customer-summary, due-date-summary ou maturities

Cuidado

Operações financeiras e documentais devem ser chamadas apenas pelo backend da integração, nunca diretamente de um navegador público com tokens persistentes.