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.
-
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": "..." } } -
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 oreciboda 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.
| Campo | Obrigatório | Regra |
|---|---|---|
numero-origem | sim | Até 60 caracteres. Identifica o bilhete no seu sistema. Veja Reenvio |
serie | sim | 1 a 3 dígitos, sem zero à esquerda |
ind-pres | sim | 1 presencial, 2 internet, 3 teleatendimento, 4 entrega em domicílio, 5 presencial fora do estabelecimento, 9 outros |
uf-ini / c-mun-ini | sim | UF e município de início da viagem |
uf-fim / c-mun-fim | sim | UF (EX para exterior) e município de fim |
passagem | sim | c-loc-orig, x-loc-orig, c-loc-dest, x-loc-dest, dh-emb, dh-validade e passageiro |
passagem.passageiro | sim | x-nome, tp-doc (1 RG, 2 título de eleitor, 3 passaporte, 4 CNH, 5 outros), n-doc; cpf opcional |
viagem | sim | c-percurso, x-percurso, dh-viagem. Opcionais: tp-viagem (00), tp-serv (1), tp-acomodacao (1), tp-trecho (1), poltrona, plataforma |
valor | sim | v-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) |
icms | sim | tipo 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) |
pagamentos | sim | 1 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 |
comprador | não | Se 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-emitente | não | Padrã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 mesmonumero-origem: é uma emissão nova, com recibo novo; -
depois de um erro técnico (
999), reenvie com o mesmonumero-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
004com 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
999e nada é emitido. Tente mais tarde.
Vale também quando a resposta se perdeu no caminho (o recibo anterior responde
999sem dados do bilhete): o bilhete é localizado pelo recibo. Se a tentativa anterior ainda estiver em andamento, o reenvio é recusado na hora comstatus: "400"no camponumero-origem: aguarde alguns minutos e reenvie o mesmo pedido.Assim um bilhete nunca sai em dobro por causa de um reenvio.
- autorizado (com atraso): ele é adotado e o recibo novo responde
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:
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.chaveousubstituicao.recibo(o recibo da emissão do bilhete substituído);tp-sub:1remarcação,2transferência,3transferê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-origemda 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
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.
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.
curl -X POST $BASE/bpe/alteracao-poltrona \ -H "Authorization: Token $TOKEN" -H "Content-Type: application/json" \ -d '{ "chave": "35261211222333000181630010000001231000000010", "poltrona": "14" }'Excesso de bagagem
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ódigo | Emissão / substituição | Eventos |
|---|---|---|
001 | Registrado na fila. | Registrado na fila. |
400 | Recusado na hora: campo (data.campo) ou cadastro da empresa. | Bilhete não encontrado, não autorizado ou já cancelado; campo inválido. |
002 / 003 | Na fila / sendo emitido. Aguarde. | Na fila / sendo enviado. |
004 | Autorizado (chave, protocolo, qr-code). | Evento registrado. |
010 | Autorizado e depois cancelado. | Cancelamento registrado. |
900 | Recusado pela SEFAZ ou pela validação do serviço. | Evento recusado. |
999 | Erro técnico. Reenvie com o mesmo numero-origem (a SEFAZ é consultada antes). | Erro técnico. |
500 | Recibo inexistente ou de outra empresa. | Idem. |
Veja também Códigos de status.