Importar planilha

Emita centenas de notas a partir de uma planilha. Você envia um .csv ou .xlsx, a Corvo lê e confere cada linha em segundo plano, você revê os problemas se quiser, e então emite tudo. O mesmo fluxo existe no painel (Notas, Importar planilha) e para assistentes por MCP.

Como funciona

• POST /v1/imports envia o arquivo e responde na hora com o id da importação.
• Consulte GET /v1/imports/:id até o status ser ready. Cada linha é conferida sozinha: uma linha ruim nunca impede as outras.
• Revisão opcional: GET /v1/imports/:id/rows?status=invalid mostra os problemas, PATCH /v1/imports/:id/rows/:line corrige um, GET /v1/imports/:id/errors.csv baixa só os erros.
• POST /v1/imports/:id/emit emite as linhas válidas. Acompanhe os contadores até o status ser done.

A planilha

A primeira linha é o cabeçalho. Os nomes são reconhecidos sem diferenciar maiúsculas e acentos, em português ou inglês (valor ou amount). O CSV pode usar ; ou , e codificação UTF-8, UTF-16 ou do Windows. Os valores aceitam 1.234,56, 1234.56 e R$ 1.234,56; as datas aceitam dd/mm/aaaa (também 7/11/2026, 07-11-2026 e 07.11.2026) e aaaa-mm-dd. Colunas que não casam com nenhum nome abaixo são ignoradas e listadas em unknown_columns da importação. Fórmulas nunca são executadas: só o valor guardado é lido.

Regras

Status e contadores

counters: total, valid, invalid, accepted (salvas e na fila de emissão), authorized (a prefeitura já autorizou), awaiting_credits (recusadas por falta de créditos: **não são erro**), failed (linhas inválidas mais as notas que a prefeitura recusou), pending (ainda aguardando ou em andamento), valid_amount e awaiting_amount em reais. Durante a emissão, authorized_amount, pending_amount e failed_amount mostram em reais quanto já foi autorizado, quanto está em andamento e quanto foi recusado (linhas inválidas nunca entram, porque não chegaram a ser enviadas).

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
    }
  }
}

Outras rotas

Quando os créditos acabam

Ficar sem créditos não é falha da planilha. A emissão para, as linhas que não foram enviadas ficam como awaiting_credits (ERROR_MONTHLY_LIMIT_EXCEEDED, ERROR_INSUFFICIENT_CREDITS e códigos parecidos nas linhas) e nada se perde. Recarregue os créditos e chame POST /v1/imports/:id/emit de novo: só essas linhas são enviadas, com as mesmas chaves. Você reencontra a importação depois com GET /v1/imports.

Em test, emitir não usa créditos, então este é o jeito de experimentar uma planilha antes da de verdade. Use CPFs e CNPJs reais em live: a prefeitura confere no cadastro e recusa os inventados.

Pelo MCP

Assistentes podem fazer o mesmo fluxo com as ferramentas import_create, import_list, import_get, import_rows, import_fix_row, import_emit e import_discard (veja a página de MCP). Uma planilha enviada por MCP é texto dentro da mensagem: CSV em content (ou um .xlsx em content_base64), até 1 MB; arquivos maiores vão por POST /v1/imports.