Import spreadsheet

Issue hundreds of invoices from one spreadsheet. You upload a .csv or .xlsx, Corvo reads and checks every row in the background, you review the problems if you want, and then you issue everything. The same flow is available in the dashboard (Invoices, Import spreadsheet) and to assistants through MCP.

How it works

• POST /v1/imports uploads the file and answers right away with the import id.
• Poll GET /v1/imports/:id until status is ready. Each row is checked on its own: a bad row never stops the others.
• Optional review: GET /v1/imports/:id/rows?status=invalid shows the problems, PATCH /v1/imports/:id/rows/:line fixes one, GET /v1/imports/:id/errors.csv downloads only the errors.
• POST /v1/imports/:id/emit issues the valid rows. Follow the counters until status is done.

The spreadsheet

The first line is the header. Names are matched without caring about case or accents, in Portuguese or English (valor or amount). CSV may use ; or , and UTF-8, UTF-16 or Windows encodings. Amounts accept 1.234,56, 1234.56 and R$ 1.234,56; dates accept dd/mm/aaaa (also 7/11/2026, 07-11-2026 and 07.11.2026) and aaaa-mm-dd. Columns that match no name below are ignored and listed in unknown_columns of the import. Formulas are never run: only the stored value is read.

Rules

Status and counters

counters: total, valid, invalid, accepted (saved and queued for issuing), authorized (the city already authorized), awaiting_credits (turned away for lack of credits: **not an error**), failed (invalid rows plus invoices the city refused), pending (still waiting or in progress), valid_amount and awaiting_amount in BRL. While issuing, authorized_amount, pending_amount and failed_amount show in BRL how much is already authorized, still in progress and refused (invalid rows never count, since they never went out).

curl -X POST "$BASE_URL/imports" \
  -H "X-API-Key: $CORVO_API_KEY" \
  -F "file=@notas-novembro.csv" \
  -F "companyId=5b0e7c5a-5d0b-4f45-8d6c-3a2a1e9d7f20"

{ "data": { "id": "576905ae-1707-4848-9ed6-5a6e51800b74", "status": "processing", "duplicate_of": null } }

curl "$BASE_URL/imports?limit=10" \
  -H "X-API-Key: $CORVO_API_KEY"

{ "data": [ /* imports, like GET /v1/imports/:id */ ] }

curl "$BASE_URL/imports/576905ae-1707-4848-9ed6-5a6e51800b74" \
  -H "X-API-Key: $CORVO_API_KEY"

{
  "data": {
    "id": "576905ae-1707-4848-9ed6-5a6e51800b74",
    "status": "ready",
    "file_name": "notas-novembro.csv",
    "company_id": null,
    "error_code": null,
    "rows_expected": 300,
    "unknown_columns": [],
    "emit_started_at": null,
    "emit_finished_at": null,
    "created_at": "2026-11-07T13:05:21.000Z",
    "counters": {
      "total": 300,
      "valid": 297,
      "invalid": 3,
      "accepted": 0,
      "authorized": 0,
      "awaiting_credits": 0,
      "valid_amount": 718602.19,
      "awaiting_amount": 0,
      "failed": 3,
      "pending": 297,
      "authorized_amount": 0,
      "pending_amount": 718602.19,
      "failed_amount": 0
    }
  }
}

curl "$BASE_URL/imports/576905ae-1707-4848-9ed6-5a6e51800b74/rows?status=invalid&limit=50" \
  -H "X-API-Key: $CORVO_API_KEY"

{ "data": [
  {
    "line": 42,
    "data": {
      "amount": "abc",
      "competenceDate": "2026-11-07",
      "companyTaxId": "61469487000140",
      "customer": { "name": "Maria da Silva", "taxId": "52998224725" },
      "service": { "description": "Consultoria mensal" }
    },
    "status": "invalid",
    "error_code": "ERROR_VALIDATION",
    "error_message": "Request validation failed",
    "invoice_id": null
  }
], "pagination": { "limit": 50, "hasMore": false, "nextCursor": null } }

curl -X PATCH "$BASE_URL/imports/576905ae-1707-4848-9ed6-5a6e51800b74/rows/42" \
  -H "X-API-Key: $CORVO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "item": { "amount": 1500.5 } }'

{ "data": {
  "line": 42,
  "data": {
    "amount": 1500.5,
    "competenceDate": "2026-11-07",
    "companyTaxId": "61469487000140",
    "customer": { "name": "Maria da Silva", "taxId": "52998224725" },
    "service": { "description": "Consultoria mensal" }
  },
  "status": "valid",
  "error_code": null,
  "error_message": null,
  "invoice_id": null
} }

curl -X POST "$BASE_URL/imports/576905ae-1707-4848-9ed6-5a6e51800b74/emit" \
  -H "X-API-Key: $CORVO_API_KEY"

{
  "data": {
    "id": "576905ae-1707-4848-9ed6-5a6e51800b74",
    "status": "emitting",
    "file_name": "notas-novembro.csv",
    "company_id": null,
    "error_code": null,
    "rows_expected": 300,
    "unknown_columns": [],
    "emit_started_at": null,
    "emit_finished_at": null,
    "created_at": "2026-11-07T13:05:21.000Z",
    "counters": {
      "total": 300,
      "valid": 297,
      "invalid": 3,
      "accepted": 0,
      "authorized": 0,
      "awaiting_credits": 0,
      "valid_amount": 718602.19,
      "awaiting_amount": 0,
      "failed": 3,
      "pending": 297,
      "authorized_amount": 0,
      "pending_amount": 718602.19,
      "failed_amount": 0
    }
  }
}

Other routes

When credits run out

Running out of credits is not a failure of the spreadsheet. Issuing stops, the rows that were not sent are kept as awaiting_credits (ERROR_MONTHLY_LIMIT_EXCEEDED, ERROR_INSUFFICIENT_CREDITS and similar codes on the rows) and nothing is lost. Top up your credits and call POST /v1/imports/:id/emit again: only those rows are sent, with the same keys. You can find the import later with GET /v1/imports.

In test, issuing does not use credits, so this is the way to try a spreadsheet before the real one. Use real CPFs and CNPJs in live: the city checks them against the tax registry and refuses invented ones.

Through MCP

Assistants can run the same flow with the tools import_create, import_list, import_get, import_rows, import_fix_row, import_emit and import_discard (see the MCP page). A spreadsheet sent through MCP is text inside the message: CSV in content (or an .xlsx in content_base64), up to 1 MB; bigger files go through POST /v1/imports.