The Java SDK for the Corvo NFS-e API. Register companies, calculate taxes, issue Brazilian service invoices (NFS-e), follow them by webhook and download the PDF and XML, from Java 17+.
- Result-style errors. Every call returns
CompletableFuture<Result<T>>with eitherResult.Ok(data)orResult.Err(CorvoApiError). The error carries the server's stablecode, the HTTPstatus, therequestId, field-leveldetailsandretryAfter. Pattern-match it withswitch. - Pagination built in. Lists return
{ data, pagination }, anditerate(...)walks every page as aStream<T>. - Safe retries. Issuing an invoice and sending an email accept an idempotency key.
- Webhook signature check in constant time.
- Built on
java.net.http.HttpClientand Jackson. Library only, no CLI.
Full API reference: https://corvo.tech/en/docs.
<dependency>
<groupId>tech.corvo</groupId>
<artifactId>corvo-nfse</artifactId>
<version>0.2.0</version>
</dependency>Start with a corvo_test_... key: invoices issued with it have no fiscal value.
import technology.corvo.nfse.Corvo;
import technology.corvo.nfse.transport.Result;
Corvo corvo = Corvo.builder()
.apiKey("corvo_test_...") // or set CORVO_API_KEY
// .baseUrl("https://api.corvo.tech") // default; also read from CORVO_BASE_URL
.build();
Result<Paginated<Company>> result = corvo.companies().list(10, null).join();
switch (result) {
case Result.Ok<Paginated<Company>> ok ->
ok.data().data().forEach(c -> System.out.println(c.legalName()));
case Result.Err<Paginated<Company>> err -> {
CorvoApiError e = err.error();
System.err.println(e.code() + " " + e.status() + " " + e.requestId());
}
}Corvo.builder().build() is the only call that throws (IllegalArgumentException): it fails fast when no API key is configured or the base URL is invalid. All resource methods return CompletableFuture<Result<T>>: compose them with thenApply/thenCompose, or call .join() for blocking style.
CompanyCreateParams params =
CompanyCreateParams.of("Empresa Exemplo Ltda", "11222333000181", "Simples Nacional", "3550308") // "MEI" or "Simples Nacional": the only regimes Corvo serves
.withSimplesRate("6.54") // required for Simples Nacional: effective DAS rate (%), ignored for MEI
.withDefaultServiceCode("010101"); // optional: used when an invoice omits service.code
Result<Company> company = corvo.companies().create(params).join();In live, also upload the A1 certificate (below). The company is ready when status() is "ready" and setupGaps() is empty.
Nothing is issued, stored or charged.
InvoiceCreateParams params = InvoiceCreateParams.of(
null, // no customer
InvoiceCreateParams.Service.ofDescription("Consultoria"),
1500.0,
"2026-10-16")
.withCompanyTaxId("11222333000181");
Result<InvoiceCalculation> estimate = corvo.invoices().calculate(params).join();
// status() is "ready" or "blocked": a fiscal gap is data, not an error.Issuing is asynchronous: a successful call means the request was accepted, not that the invoice is authorized. Follow the status with invoices().get(id) or webhooks.
InvoiceCreateParams params = InvoiceCreateParams.of(
// The customer is optional; when sent, taxId (CPF or CNPJ) is required.
InvoiceCreateParams.Customer.of("Cliente", "52998224725").withEmail("cliente@example.com"),
InvoiceCreateParams.Service.ofDescription("Consultoria"), // code and city default to the company's
150.5,
"2026-10-16")
.withCompanyTaxId("11222333000181") // or withCompanyId(...)
.withOptions(InvoiceCreateParams.Options.sendEmail(true));
Result<Invoice> invoice = corvo.invoices().create(params, "order-42").join(); // the same key never issues twiceUse Options.schedule() with a future competence date to schedule the issuance.
To declare a deduction from the ISS base, use .withDeduction(...) (greater than 0 and less than amount minus discount). The invoice is still issued for the full amount, and you are responsible for the declared value.
createBatch takes 1 to 50 items (they can belong to different companies). Items are checked one by one: valid ones are saved together, invalid ones come back rejected and are not saved. Set an idempotency key per item, so repeating the batch after a timeout returns the saved ones with replayed.
Result<InvoiceBatchSummary> batch = corvo.invoices().createBatch(List.of(
InvoiceBatchItem.of(params.withExternalId("row-2"), "sheet-row-2"),
InvoiceBatchItem.of(params.withExternalId("row-3"), "sheet-row-3"))).join();
if (batch instanceof Result.Ok<InvoiceBatchSummary> ok) {
for (InvoiceBatchSummary.Result item : ok.data().results()) {
if ("rejected".equals(item.status())) {
System.out.println(item.index() + " " + item.error().code() + " " + item.error().message());
}
}
}The route allows 10 batches per minute per tenant (429 with Retry-After).
Result<Invoice> cancelled = corvo.invoices()
.cancel(invoiceId, InvoiceCancelParams.of("issue_error", "Wrong amount on the invoice"))
.join(); // reason: "issue_error" | "service_not_provided" | "other"queued: cancelled at once,status()is"cancelled"withcancelledAt()set.authorized:status()is"cancelling"while the cancellation is processed at the Sefin. The issuance credit is not refunded.processing: stays"processing"withcancellationRequestedAt()set and is cancelled once authorized.
The description (15 to 255 characters) is required for an authorized or processing invoice and optional for a queued one. Read the invoice again (or listen to the nfse.invoice.cancelled and nfse.invoice.cancellation_rejected webhooks) to see the outcome: cancelled, or back to authorized with lastErrorCode() when the cancellation was rejected.
try (Stream<Invoice> invoices = corvo.invoices().iterate(null, "authorized", null, null, null, null, null)) {
invoices.forEach(inv -> System.out.println(inv.nfseNumber()));
}iterate(...) throws CorvoApiError (unchecked) if a page fails, since a Stream has no other error channel.
The invoice must be authorized and have its documents ready.
if (corvo.invoices().pdf(invoiceId).join() instanceof Result.Ok<DownloadedFile> ok) {
Files.write(Path.of("nfse.pdf"), ok.data().content());
}byte[] p12 = Files.readAllBytes(Path.of("certificado.p12"));
Result<Certificate> cert = corvo.certificates().upload("comp_1", p12, "senha", null).join();// rawBody: the request body bytes exactly as received; the header is X-Corvo-Signature.
boolean ok = CorvoWebhooks.verifySignature(rawBody, signatureHeader, "whsec_xxx");Webhook.WEBHOOK_EVENTS lists the 11 events you can subscribe to. The webhook.test event is only sent by webhooks().test(id). Deduplicate by the event id: the same event can be delivered more than once.
Result<Company> result = corvo.companies().get("comp_1").join();
if (result instanceof Result.Err<Company> err) {
CorvoApiError e = err.error();
switch (e.status()) {
case 400 -> e.details().forEach(d -> System.err.println(d.field() + ": " + d.message()));
case 429 -> System.err.println("Rate limited, retry after " + e.retryAfter() + "s");
default -> System.err.println(e.code() + ": " + e.getMessage());
}
}code is the API's ERROR_* code, falling back to http_<status>. network_error (status 0) means the request never reached the server; timeout (status 0) means it exceeded the configured timeout.
- companies: create, get, update, remove, list, iterate
- certificates: upload, list, remove
- invoices: create, createBatch, calculate, get, list, iterate, events, pdf, xml, downloadUrl, sendEmail, cancel
- webhooks: list, create, remove, test; deliveries: list, iterate, stats, retry
- credits: balance, plans, history, iterateHistory
- billing: plan, usage
- plans: list, get, quote (public price catalog)
- health: live, ready
Changing plans and the billing portal exist only in the dashboard, so they are not in the SDK.
Corvo.builder() options: apiKey (or CORVO_API_KEY), baseUrl (or CORVO_BASE_URL, default https://api.corvo.tech), prefix (default v1), timeout (default 30s) and allowInsecureHttp (http:// is only accepted for loopback and private hosts unless enabled). Keys are corvo_test_... or corvo_live_... and belong to one account and environment; the key decides the environment.
mvn verify # build + unit tests (the contract test skips without env)The contract test runs only when CORVO_API_KEY and CORVO_BASE_URL point to a reachable instance.
MIT, see LICENSE.