APIs de parceiro
Dados fiscais para impressão
Obtenha os dados fiscais imprimíveis de um pedido — emissor, loja, comprador, referências do documento e campos específicos por país. Use para renderizar um recibo ou nota fiscal do lado da sua integração.
GET
Retorna o contexto fiscal consolidado de um pedido específico — os dados que seu point-of-sale ou backoffice renderizaria em um recibo/nota fiscal impresso ou digital. Expõe:
Mesmo caminho, mesma autenticação, mesmos parâmetros. O que muda é a resposta:
O que a v2 acrescenta, e por que pode te importar:
- Contexto do emissor — entidade legal, gov ID, info de loja, inscrição estadual
- Referências fiscais por país — chave de acesso, CUFE, clave de acceso, CAE, folio, etc., conforme país
- Contexto do comprador — destinatário, com flag de anônimo/consumidor final
- Resumo do pedido — código, status, dia de negócio
Duas versões, as duas vivas
A v1 não se mexeu e não vai se mexer. Se a sua integração já a consome, você não precisa fazer
nada: os mesmos campos e os mesmos valores de sempre.A v2 existe porque uma das mudanças não é aditiva —
ambiente é o mesmo campo com outro
valor— e mudá-lo na v1 tiraria o dado debaixo dos pés de um caixa já integrado. Não há data de
descontinuação para a v1.fiscalRepresentation— o documento tal como foi numerado, com o seu histórico. É o que torna imprimível uma nota de crédito: trazcompensates(qual nota anula, com o motivo já redigido) e essa nota inteira emhistory. Na v1 essa informação não existe.- Rótulos resolvidos —
FACTURA,NOTA DE CREDITO RIDE,EMISION NORMAL,PRODUCCION: os códigos do órgão já traduzidos, para que você não carregue a tabela dele dentro do seu POS. - A data de emissão (
issuedAt) do comprovante, que a v1 não expõe.
Autenticação
string
obrigatório
Sua API key do Fire com scope
orders:read. Vendor-scoped: a API key deve pertencer ao mesmo vendor dono da loja/pedido.Path parameters
string
obrigatório
Qualquer uma das três referências públicas do pedido:
Não precisa traduzir: use o id que você já conhece.
Query parameters
O vendor é resolvido a partir da sua API key (vendor-scoped). O parâmetro
vendorId foi removido — se enviado, é ignorado.Resposta
object
Referências fiscais comuns do documento, independente do país.
object
Referências do documento específicas por país. O formato varia conforme
fiscal.countryCode. Exemplos:- BR:
chaveAcesso(44 dígitos),serie,serialNumber - CO:
cufe,prefijo,numeroDian - EC:
numeroComprobante,claveAcceso(49 dígitos),numeroAutorizacion,ambiente - CL:
folio,ted,tipoDte,trackId - AR:
cae,fechaVtoCae,puntoVenta,numeroComprobante,tipoComprobante - VE:
numeroControl,numeroFactura,rifEmisor
Só na v2: os valores vêm traduzidos, não no código do órgão. No Equador o provedor manda
ambiente: "2" —é assim que o SRI define— e na v2 chega "PRODUCCION", que é o que vai
impresso. Na v1 esse campo continua trazendo "2", sem mudanças.
É o mesmo critério da numeração fiscal: traduzir isso do lado do ponto de venda
significaria que cada integrador carrega a sua cópia da tabela do órgão, e o primeiro que a
copiar errado imprime “PRUEBAS” numa nota de produção.Um país sem tabela de rótulos devolve os seus valores tal como vieram.object
Só na v2. O documento tal como foi numerado, com o seu histórico e os rótulos já resolvidos.
Na v1 esta chave não existe.Dentro da v2, aparece somente quando a venda passou pelo Fiscal Gateway. Se o comércio fiscaliza apenas por
callback —Brasil, agregadores, ou o gateway desativado— a chave não vem na resposta. Não chega
como
null: não está lá.É o mesmo formato que viaja em data.fiscalRepresentation dos eventos, então quem aprende a ler
um lê o outro.Por que está separado de
fiscal. Respondem perguntas diferentes: fiscal é o documento
com o veredito do órgão por cima —estado, protocolo, data de autorização— e muda quando o
órgão responde. Este outro é o que foi impresso no caixa e não muda nunca.Quando o SRI autoriza, fiscal.status passa a authorized e aparecem o PDF e o XML, mas o
número do comprovante continua o mesmo. São dois fatos, não duas versões do mesmo.object | null
Entidade legal que emite o documento.
object | null
Info a nível de loja para o cabeçalho impresso.
object
Destinatário do documento.
object
Contexto mínimo do pedido para cross-reference.
O que muda ao imprimir na Colômbia, em relação ao exemplo do Equador acima:
graphicénull. O QR é a URL do catálogo da DIAN e trafega emcountryData.qrCode. No Equador o QR deriva da chave de acesso e por isso é entregue à parte; aqui já chega resolvido, e duplicá-lo daria duas cópias que podem divergir.- Os rótulos são os da DIAN:
FACTURA ELECTRONICA DE VENTAem vez deFACTURA, eVALIDACION PREVIAem vez deEMISION NORMAL. ambientechega traduzido igual ao Equador, mas atenção ao código de origem: a DIAN usa1para produção e o SRI usa para homologação. O Fire resolve isso, e por isso os dois leemPRODUCCIONaqui.authorizationProtocolleva o CUFE, que é o que identifica o documento perante o órgão — o equivalente da chave de acesso equatoriana.
store, company e order não mudam por país, então são omitidos aqui e valem
os do exemplo do Equador.Padrões comuns
- Fetch no momento da impressão. Chame este endpoint na hora de imprimir/renderizar e persista a resposta se precisar de artefatos duráveis —
pdfUrlexmlUrlpodem ser URLs assinadas que expiram. - Flag de consumidor final. Sempre verifique
buyer.isFinalConsumerantes de renderizar detalhes do comprador. Para consumidores anônimos em BR,govIdNumberé"00000000000"e os outros campos do comprador sãonull. - UI específica por país. Use
fiscal.countryCodepara despachar para o template de renderização correto — DANFCE para BR NFC-e, estilo DIAN para CO, SRI para EC, etc.
Relacionado
Evento order.completed
O snapshot completo do pedido — muito mais rico que fiscal-print, usado para integrações não-print.
Evento order.invoiced
Apenas Brasil — dispara quando a SEFAZ autoriza; carrega as mesmas referências fiscais.
Callback fiscal
O endpoint inbound que seu provedor fiscal usa para atualizar o estado fiscal.