Pular para o conteúdo

Emitir BP-e

O BP-e (Bilhete de Passagem Eletrônico, modelo 63) é o documento fiscal do transporte rodoviário de passageiros. A API do FazNota emite o bilhete, devolve chave, protocolo e QR Code, e registra os eventos do passageiro: cancelamento, não-embarque, alteração de poltrona e excesso de bagagem. A remarcação e a transferência são feitas por substituição, que emite um bilhete novo no lugar do anterior.

Contrato completo, substituição e consulta por recibo desde a versão 3.21.0.

Pré-requisitos no cadastro da empresa (FazNota)

  • Certificado digital A1. O A3 não serve, porque exige o token físico para assinar.
  • Ambiente SEFAZ definido (homologação ou produção). O bilhete segue esse ambiente.
  • Inscrição estadual do emitente.
  • Emitente (CNPJ, razão social, endereço) e responsável técnico vêm do cadastro. Não envie.

Sem esses dados, o pedido é recusado na hora com status: "400".

Fluxo

Como toda operação da v3, o BP-e é assíncrono: você envia o pedido, recebe um recibo e consulta o resultado.

  1. Emitir

    Terminal window
    curl -X POST $BASE/bpe/emissao \
    -H "Authorization: Token $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
    "numero-origem": "VENDA-000123",
    "serie": "1",
    "ind-pres": "1",
    "uf-ini": "SP", "c-mun-ini": "3550308",
    "uf-fim": "RJ", "c-mun-fim": "3304557",
    "passagem": {
    "c-loc-orig": "3550308", "x-loc-orig": "Sao Paulo - Tiete",
    "c-loc-dest": "3304557", "x-loc-dest": "Rio de Janeiro - Novo Rio",
    "dh-emb": "2026-12-10T08:00:00-03:00",
    "dh-validade": "2026-12-10T23:59:59-03:00",
    "passageiro": { "x-nome": "Maria da Silva", "tp-doc": "1", "n-doc": "123456789" }
    },
    "viagem": {
    "c-percurso": "SP-RJ", "x-percurso": "Sao Paulo - Rio de Janeiro",
    "dh-viagem": "2026-12-10T08:00:00-03:00", "poltrona": "12"
    },
    "valor": {
    "v-bp": 120.00, "v-desconto": 0, "v-pgto": 120.00, "v-troco": 0,
    "comp": [ { "tp-comp": "01", "v-comp": 110.00 }, { "tp-comp": "03", "v-comp": 10.00 } ]
    },
    "icms": { "tipo": "00", "v-bc": 120.00, "p-icms": 12.00, "v-icms": 14.40 },
    "pagamentos": [ { "t-pag": "06", "v-pag": 120.00 } ]
    }'

    Resposta:

    { "status": "001", "descricao": "Bilhete de passagem registrado com sucesso.",
    "data": { "recibo": "..." } }
  2. Consultar o resultado

    Faça polling com intervalo mínimo de 2 segundos:

    Terminal window
    curl $BASE/bpe/{recibo} -H "Authorization: Token $TOKEN"

    Quando a SEFAZ autoriza:

    {
    "status": "004",
    "descricao": "Bilhete de passagem autorizado pela SEFAZ.",
    "data": {
    "processo": "emissao",
    "situacao": "AUTORIZADO",
    "chave": "35261211222333000181630010000001231000000010",
    "protocolo": "135260000000001",
    "qr-code": "https://...?chBPe=...&tpAmb=1",
    "serie": "1",
    "numero": "123",
    "ambiente": "producao",
    "data-emissao": "2026-12-01 10:00:00",
    "data-autorizacao": "2026-12-01 10:00:02",
    "valor": "120.00",
    "c-stat": "100",
    "x-motivo": "Autorizado o uso do BP-e"
    }
    }

    Guarde a chave: os eventos e a substituição a usam (ou o recibo da emissão).

Campos da emissão

Valores aceitam número ou texto com até 2 casas (120, 120.00). Datas levam o fuso (2026-12-10T08:00:00-03:00). Textos aceitam só caracteres Latin-1: travessão (—), aspas curvas e emoji são recusados. Municípios usam o código IBGE de 7 dígitos.

CampoObrigatórioRegra
numero-origemsimAté 60 caracteres. Identifica o bilhete no seu sistema. Veja Reenvio
seriesim1 a 3 dígitos, sem zero à esquerda
ind-pressim1 presencial, 2 internet, 3 teleatendimento, 4 entrega em domicílio, 5 presencial fora do estabelecimento, 9 outros
uf-ini / c-mun-inisimUF e município de início da viagem
uf-fim / c-mun-fimsimUF (EX para exterior) e município de fim
passagemsimc-loc-orig, x-loc-orig, c-loc-dest, x-loc-dest, dh-emb, dh-validade e passageiro
passagem.passageirosimx-nome, tp-doc (1 RG, 2 título de eleitor, 3 passaporte, 4 CNH, 5 outros), n-doc; cpf opcional
viagemsimc-percurso, x-percurso, dh-viagem. Opcionais: tp-viagem (00), tp-serv (1), tp-acomodacao (1), tp-trecho (1), poltrona, plataforma
valorsimv-bp e v-pgto; v-desconto e v-troco (padrão 0); comp com ao menos um componente (tp-comp 01 tarifa, 02 pedágio, 03 taxa de embarque, 04 seguro, 05 TMR, 06 SVI, 99 outros)
icmssimtipo 00, 20, 45, 90 ou SN. 00/20/90 exigem v-bc, p-icms, v-icms; 20 exige p-red-bc; 45 aceita cst (40, 41, 51)
pagamentossim1 a 10 formas: t-pag (01 dinheiro, 02 cheque, 03 crédito, 04 débito, 05 vale transporte, 06 PIX, 99 outros) e v-pag
compradornãoSe vier: x-nome, cpf ou cnpj, e endereco com x-lgr, nro, x-bairro, c-mun, x-mun, uf (cep e x-cpl opcionais)
nm-fantasia-emitentenãoPadrão: a razão social do cadastro

Campo ausente ou fora da regra volta na hora com status: "400" e o nome do campo:

{ "status": "400", "descricao": "passagem.dh-emb e' obrigatoria no formato AAAA-MM-DDTHH:MM:SS-03:00 (com o fuso).",
"data": { "campo": "passagem.dh-emb", "erro": "..." } }

Reenvio

Envie sempre um numero-origem estável por bilhete (por exemplo, o número da venda):

  • reenviar com o mesmo valor enquanto o bilhete está na fila, autorizado ou cancelado devolve o recibo original, sem emitir outro;

  • depois de uma recusa (900), corrija o dado e reenvie com o mesmo numero-origem: é uma emissão nova, com recibo novo;

  • depois de um erro técnico (999), reenvie com o mesmo numero-origem. Se o bilhete anterior já tinha número (por exemplo, a SEFAZ não respondeu a tempo), o reenvio consulta a SEFAZ por aquele bilhete antes de emitir:

    • autorizado (com atraso): ele é adotado e o recibo novo responde 004 com a chave dele;
    • a SEFAZ não o conhece: ele é emitido de novo com o mesmo número;
    • a consulta não responde: o recibo novo responde 999 e nada é emitido. Tente mais tarde.

    Vale também quando a resposta se perdeu no caminho (o recibo anterior responde 999 sem dados do bilhete): o bilhete é localizado pelo recibo. Se a tentativa anterior ainda estiver em andamento, o reenvio é recusado na hora com status: "400" no campo numero-origem: aguarde alguns minutos e reenvie o mesmo pedido.

    Assim um bilhete nunca sai em dobro por causa de um reenvio.

Substituição (remarcação ou transferência)

A substituição emite um BP-e novo (tpBPe 3) que aponta o bilhete anterior. O corpo é o mesmo da emissão, com os dados novos, mais o grupo substituicao:

Terminal window
curl -X POST $BASE/bpe/substituicao \
-H "Authorization: Token $TOKEN" -H "Content-Type: application/json" \
-d '{
"numero-origem": "VENDA-000123-REMARCACAO-1",
"substituicao": { "chave": "35261211222333000181630010000001231000000010", "tp-sub": "1" },
"serie": "1", "ind-pres": "1",
"...": "demais campos da emissão, com a nova data/poltrona"
}'
  • substituicao.chave ou substituicao.recibo (o recibo da emissão do bilhete substituído);
  • tp-sub: 1 remarcação, 2 transferência, 3 transferência e remarcação;
  • só bilhete autorizado da sua empresa pode ser substituído;
  • o registro de “BP-e substituído” no bilhete original é feito pela própria SEFAZ;
  • o numero-origem da substituição é separado do da emissão: use um valor próprio.

O resultado sai em GET /bpe/{recibo}, como uma emissão (004 com a nova chave).

Eventos

Nos quatro eventos, identifique o bilhete por chave ou por recibo (o da emissão ou da substituição). O bilhete precisa ser da sua empresa e estar autorizado. Cada evento devolve o seu próprio recibo, consultado em GET /bpe/{recibo}: 004 registrado (010 no cancelamento) ou 900 recusado pela SEFAZ, com c-stat e x-motivo.

Cancelar

Terminal window
curl -X POST $BASE/bpe/cancelamento \
-H "Authorization: Token $TOKEN" -H "Content-Type: application/json" \
-d '{ "chave": "35261211222333000181630010000001231000000010",
"justificativa": "Viagem cancelada a pedido do passageiro" }'

A justificativa tem de 15 a 255 caracteres. Bilhete já cancelado é recusado na hora.

Não-embarque

O passageiro não se apresentou. Uma vez por bilhete.

Terminal window
curl -X POST $BASE/bpe/nao-embarque \
-H "Authorization: Token $TOKEN" -H "Content-Type: application/json" \
-d '{ "recibo": "...", "justificativa": "Passageiro nao compareceu ao embarque" }'

Alteração de poltrona

Pode ser repetida; cada alteração recebe a próxima sequência do evento.

Terminal window
curl -X POST $BASE/bpe/alteracao-poltrona \
-H "Authorization: Token $TOKEN" -H "Content-Type: application/json" \
-d '{ "chave": "35261211222333000181630010000001231000000010", "poltrona": "14" }'

Excesso de bagagem

Terminal window
curl -X POST $BASE/bpe/excesso-bagagem \
-H "Authorization: Token $TOKEN" -H "Content-Type: application/json" \
-d '{ "chave": "35261211222333000181630010000001231000000010", "q-bagagem": "2", "v-tot-bag": 35.00 }'

q-bagagem tem até 20 caracteres; v-tot-bag é opcional (padrão 0).

Códigos de status

CódigoEmissão / substituiçãoEventos
001Registrado na fila.Registrado na fila.
400Recusado na hora: campo (data.campo) ou cadastro da empresa.Bilhete não encontrado, não autorizado ou já cancelado; campo inválido.
002 / 003Na fila / sendo emitido. Aguarde.Na fila / sendo enviado.
004Autorizado (chave, protocolo, qr-code).Evento registrado.
010Autorizado e depois cancelado.Cancelamento registrado.
900Recusado pela SEFAZ ou pela validação do serviço.Evento recusado.
999Erro técnico. Reenvie com o mesmo numero-origem (a SEFAZ é consultada antes).Erro técnico.
500Recibo inexistente ou de outra empresa.Idem.

Veja também Códigos de status.