Access Brazil CVM Filings with Scala
Need a Scala CVM filings API client? apicvm speaks HTTPS JSON. Use the JDK HttpClient, sttp, or http4s — there is no official Scala SDK.
The problem
JVM data pipelines for Brazilian filings often inherit brittle scrapers or one-off ZIP parsers. You want:
- Stable document IDs for caching
- Filterable lists by ticker, type, and year
- A Bearer-auth HTTP surface that fits Akka / Cats Effect / ZIO workers
Setup
export APICVM_URL='https://apicvm.dev'
export APICVM_KEY='apicvm_...'Resolve with JDK HttpClient
import java.net.URI
import java.net.http.{HttpClient, HttpRequest, HttpResponse}
import java.net.URLEncoder
val base = sys.env("APICVM_URL")
val key = sys.env("APICVM_KEY")
val q = URLEncoder.encode("PETR4", "UTF-8")
val uri = URI.create(s"$base/v1/companies/resolve?query=$q&by=ticker")
val req = HttpRequest.newBuilder(uri)
.header("Authorization", s"Bearer $key")
.GET()
.build()
val body = HttpClient.newHttpClient.send(req, HttpResponse.BodyHandlers.ofString()).body()
println(body)List DFP documents
val docsUri = URI.create(
s"$base/v1/documents?ticker=PETR4&type=DFP&year=2024&perPage=20"
)
val docsReq = HttpRequest.newBuilder(docsUri)
.header("Authorization", s"Bearer $key")
.GET()
.build()
val docs = HttpClient.newHttpClient.send(docsReq, HttpResponse.BodyHandlers.ofString()).body()Download a file
GET /v1/documents/:id/file returns the original PDF bytes. Persist with a document UUID in your object store key. File download does not consume extraction credits.
When to extract text
For page-level markdown, use POST /v1/document-text-extractions with an HTTPS callback (Pro). The API is async — poll is not available; wait for the callback. See Async PDF extraction.
Current limitations
- No official SDK; you own retries and JSON decoding
- Rate limits apply per API key (
X-RateLimit-*headers) - Student keys cannot run text extraction (
403)
Next steps
Ready to integrate?
Get an API key and start querying Brazilian CVM filings programmatically.