Emitir contra-CT-e em lote (1:1 ou em pernas)

{
  "tags": [
    "CT-e de subcontratação"
  ],
  "summary": "Emitir contra-CT-e em lote (1:1 ou em pernas)",
  "operationId": "createContraCteBatch",
  "description": "Emite **vários contra-CT-e numa chamada** e devolve um `batch_id`; a emissão roda em\nsegundo plano e o resultado por chave sai em `GET /fiscal/cte-subcontratacao/lote/{batch_id}`.\nCada CT-e da contratante precisa ter chegado antes por `POST /fiscal/cte-subcontratacao`.\n\n## Dois desenhos, um endpoint\n\n- **1:1** — um contra-CT-e integral por CT-e da contratante. `ctes[]` traz as chaves; o\n  motorista (`motorista.cpf`) e o veículo (`placa`) são os mesmos para o lote inteiro.\n- **Pernas** — um CT-e da contratante subcontratado em **trechos**: `ctes[].pernas[]`\n  descreve cada trecho com origem/destino próprios, e cada perna pode ter motorista,\n  veículo e valor próprios (o `motorista`/`placa` do lote são o padrão das pernas que não\n  informam os seus). Não misture chaves com e sem `pernas` no mesmo lote.\n\n## Valor: por chave OU rateio — nunca os dois\n\n- `ctes[].valor` (ou `pernas[].valor`) congela o valor de **cada** contra-CT-e; o fiscal\n  (`vTPrest`/`vRec`) e o repasse ao motorista saem desse valor, sem arredondar.\n- `valores.frete_bruto` no lote rateia `total ÷ N` em centavos, com o resíduo nas\n  **últimas** chaves da sequência; a soma fecha exata.\n\nInformar os dois responde `422`.\n\n## Rota do trecho\n\nPor padrão o contra-CT-e herda origem → destino da contratante. `origem`/`destino` no lote\n(ou por chave/perna) declaram a rota REAL do trecho — e é dela que saem CFOP e ICMS:\norigem na UF do emitente → `5360` (mesma UF) / `6360` (outra UF); origem fora da UF do\nemitente → `5932` (início e fim na mesma UF) / `6932`. Com regra de tributação **do tipo\nde serviço** (`tp_serv` na regra), o CFOP da regra é mantido quando a prestação começa na\nUF do emitente; o `5932`/`6932` continua imposto quando começa em outra UF. Os pares\nmunicípio × UF são validados; precisa existir regra de tributação aplicável à rota e ao\ntipo (`GET /fiscal/regras-tributacao`).\n\n## Tipo de serviço\n\n`tipo_servico` é o `ide/tpServ` de cada contra-CT-e, com precedência **perna → chave →\nlote → `1`** (subcontratação). Só `1` subcontratação, `2` redespacho e `3` redespacho\nintermediário. No redespacho a rota é o **trecho** que a subcontratada executa, não a\nviagem da contratante: `2` e `3` exigem `origem` e `destino` (na chave, no lote ou na\nperna — `422` sem eles), e um \"trecho\" igual à viagem inteira do CT-e da contratante é\nrecusado na linha com `redespacho_exige_rota`. Um CT-e da contratante vinculado a\nmultimodal (`tpServ` 4) não admite contra-CT-e (`origem_incompativel_com_tipo`; na caixa,\n`allows_counter_cte: false`). A linha de resultado devolve o `tipo_servico` com que o\ndocumento saiu (na linha `duplicated`, o tipo **pedido** — o do contra-CT-e existente está\nem `GET /fiscal/cte/{counter_cte_id}`, campo `service_type`).\n\n## Repasse ao motorista (mesma regra do CIOT)\n\n`repasse.parcelas` é a regra de parcelas do lote (posições 1..3, percentuais somando 100,\n`dias` de 0 a 30) e **vence a regra cadastrada do motorista**. Os contra-CT-e de um mesmo\nmotorista no lote formam um grupo:\n\n- **N ≥ nº de parcelas** → cada documento inteiro cai numa parcela (60/20/20 em 15 docs =\n  9/3/3 documentos, sempre ≥ 1 por parcela) — a parcela 1 libera na bipagem, a 2 na\n  conclusão, a 3 na prestação de contas;\n- **N < nº de parcelas** → cada documento é fracionado nas parcelas (60/20/20 do valor\n  dele).\n\nO bucket é decidido pela **posição no lote**, não pelo valor: com valores diferentes, a\nordem das chaves define quanto entra em cada parcela. A parcela só existe depois da\n**bipagem** do documento — consulte-a em `GET /carriers/parcelas-repasse/{documento}`\n(aceita o `counter_cte_id`).\n\n## Um modo por origem, e o que bloqueia\n\nUma chave com contra-CT-e integral ativo não aceita pernas (`origem_ja_subcontratada_1a1`)\ne vice-versa (`origem_ja_subcontratada_em_pernas`); cancelar o contra-CT-e libera o outro\nmodo. Chave já subcontratada no mesmo modo responde `duplicated` com o `counter_cte_id`\nexistente — reenviar o lote é seguro. CT-e emitido pela sua própria empresa responde\n`cte_proprio`; rota sem regra, `sem_regra_tributacao`; redespacho com o trecho igual à\nviagem inteira, `redespacho_exige_rota`; origem vinculada a multimodal,\n`origem_incompativel_com_tipo`; origem cujo repasse já foi pago não pode virar pernas.\n\nCancelar um contra-CT-e (`POST /fiscal/cte/{cte_uuid}/eventos/cancelamento`) cancela as\nparcelas ainda não pagas e tira o documento do grupo; o CT-e da contratante continua válido.\n",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ContraCteLoteInput"
        }
      }
    }
  },
  "responses": {
    "202": {
      "description": "Lote aceito; a emissão roda em segundo plano.",
      "headers": {
        "X-Request-Id": {
          "$ref": "#/components/headers/RequestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ContraCteLoteAcceptedEnvelope"
          }
        }
      }
    },
    "400": {
      "$ref": "#/components/responses/Erro400"
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "422": {
      "description": "Validação do payload (`error.details.fields`) ou regra de negócio antes de criar o lote:\n`motorista_nao_encontrado`, `veiculo_nao_encontrado` — nas pernas, o `message` aponta a\nperna (`ctes.0.pernas.2`).\n",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorEnvelope"
          }
        }
      }
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  },
  "method": "POST",
  "path": "/fiscal/cte-subcontratacao/lote",
  "parameters": []
}