FreteBarato

Envio

Envie Notas Fiscais Eletrônicas (NF-e) em Base64 para a API Frete Barato.

O endpoint de Invoice foi desenvolvido para receber e processar Notas Fiscais Eletrônicas (NF-e) em formato Base64.

Esta API permite que sistemas externos enviem documentos fiscais XML codificados em Base64, garantindo integridade, segurança e rastreabilidade no processo de recebimento.

O envio pode incluir o order_code retornado pelo cadastro de pedidos. Com ele, a NF-e é gravada nesse pedido.

O sistema realiza validações rigorosas em todas as etapas do processo, desde a estrutura do payload até a validação do conteúdo do documento decodificado.
Endpoint
https://admin.fretebarato.com/invoice/push/v1/base64/{{customer_token}}

Envie uma nota fiscal (push)

curl -X POST "https://admin.fretebarato.com/invoice/push/v1/base64/{{customer_token}}" \
  -H "Authorization: Bearer xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MinhaAplicacao ([email protected])" \
  -d '{
    "request_id": "01HZQK3F2N8PYVJ9KQ6R4WXM5T",
    "created_at": "2025-10-29T15:12:34Z",
    "document_meta": {
      "type": "nf-e",
      "model": "55",
      "nota_fiscal_id": "35150000000000000000000000000000000061234567"
    },
    "document_encoding": {
      "format": "base64",
      "mimetype": "application/xml"
    },
    "document_payload": {
      "data": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4..."
    }
  }'

Headers

KeyValueObservação
AuthorizationBearer {{token}}Token de autenticação fornecido pela equipe Frete Barato
Content-Typeapplication/jsonObrigatório para envio de payload JSON
User-AgentAplicação (e-mail para contato técnico)Opcional, mas recomendado para identificação

Parâmetros do payload

Campos de primeiro nível

ParâmetroTipoObrigatórioObservação
request_idStringSimIdentificador único da requisição (UUID ou ULID). Deve ter entre 20 e 36 caracteres
created_atStringSimData/hora de criação no formato ISO 8601 (ex: 2025-10-29T15:12:34Z)
order_codeNuméricoNãoIdentificador devolvido no cadastro de pedidos. Ausente, null ou "" envia a NF-e sem vínculo
document_metaObjectSimObjeto contendo metadados do documento fiscal
document_encodingObjectSimObjeto contendo informações de codificação do documento
document_payloadObjectSimObjeto contendo o documento codificado em Base64

Campos do objeto document_meta

ParâmetroTipoObrigatórioObservação
typeStringSimTipo do documento fiscal. Valores aceitos: nf-e (Nota Fiscal Eletrônica)
modelStringSimModelo do documento fiscal (ex: 55 para NF-e)
nota_fiscal_idStringSimChave de acesso da NF-e. Deve conter exatamente 44 caracteres numéricos

Campos do objeto document_encoding

ParâmetroTipoObrigatórioObservação
formatStringSimFormato de codificação. Atualmente aceito apenas: base64
mimetypeStringSimTipo MIME do documento original. Valores aceitos: application/xml, text/xml

Campos do objeto document_payload

ParâmetroTipoObrigatórioObservação
dataStringSimDocumento fiscal codificado em Base64. Após decodificação, deve ter no mínimo 100 bytes

Parâmetros do response

ParâmetroTipoComportamento
successBooleanIndica se a requisição foi processada com sucesso (true/false)
messageStringMensagem descritiva sobre o resultado do processamento
dataObjectObjeto contendo detalhes do documento processado (presente apenas em caso de sucesso)
data.request_idStringRetorna o identificador único da requisição enviada
data.document_metaObjectRetorna os metadados do documento processado
data.document_encodingObjectRetorna as informações de codificação do documento
data.document_sizeNumericRetorna o tamanho do documento decodificado em bytes
data.customer_codeStringRetorna o código identificador do cliente solicitante
data.received_atStringData/hora de recebimento do documento no formato Y-m-d H:i:s
data.processed_atStringData/hora de processamento do documento no formato Y-m-d H:i:s
data.order_codeNuméricoPresente apenas quando o order_code foi enviado. Pedido que recebeu a NF-e
data.linkedBooleanPresente apenas quando o order_code foi enviado. true quando a NF-e foi gravada no pedido nesta chamada e false no reenvio da mesma NF-e

Conheça as validações realizadas

A API realiza validações rigorosas em múltiplas camadas:

Tipo de validaçãoDescriçãoErro retornado
AutenticaçãoValida Bearer Token no header Authorization401 - Authentication failure
DispatcherValida versão da API (v1) e formato (base64)401 - Authentication failure / Only base64 format is supported
Token clienteValida se o token do cliente possui 32 caracteres401 - Authentication failure
Cliente existenteVerifica se o cliente existe na base de dados404 - Customer not found
Estrutura JSONValida se todos os campos obrigatórios estão presentes400 - Field campo is required
Request IDValida se é um UUID/ULID válido (20-36 caracteres)400 - Field request_id must be a valid UUID or ULID
Data ISO 8601Valida formato de data created_at400 - Field created_at must be a valid ISO 8601 datetime
Tipo documentoValida se o tipo é nf-e400 - Field document_meta.type must be one of: nf-e
Formato encodingValida se o formato é base64400 - Field document_encoding.format must be "base64"
MimetypeValida se é application/xml ou text/xml400 - Field document_encoding.mimetype must be one of: ...
Chave NF-eValida se possui exatamente 44 caracteres numéricos400 - Field document_meta.nota_fiscal_id must be exactly 44 characters
Base64 válidoValida se o Base64 pode ser decodificado400 - Invalid base64 document format
Documento vazioValida se documento decodificado não está vazio400 - Decoded document is empty
Tamanho mínimoValida se documento decodificado possui mínimo 100 bytes400 - Decoded document is too small (minimum 100 bytes)
Conteúdo vs mimetypeValida se conteúdo corresponde ao mimetype declarado400 - Document content does not match declared mimetype
order_codeCom order_code, valida o pedido, o emitente e se a NF-e ainda não foi gravada400 / 403 / 404 / 409 — veja

Trate os erros

ResponseTipoMensagemDescrição
200successInvoice received successfully (Base64 format)Nota fiscal recebida e processada com sucesso
400bad requestField campo is required / Invalid paramsParâmetros ausentes, inválidos ou fora do padrão esperado
400bad requestorder_code inválido.order_code zero, negativo, decimal, com zeros à esquerda ou com caracteres que não sejam dígitos
400bad requestNota fiscal inconsistente (emitente_cnpj).Com order_code, o emitente do XML é diferente do gravado no pedido
401unauthorizedAuthentication failureFalha na autenticação: token inválido ou versão incorreta da API
403forbiddenAccess deniedAcesso negado ao recurso solicitado
403forbiddenVocê não tem permissão para acessar este recurso.Com order_code, o CNPJ do XML não pertence à conta
404not foundCustomer not foundCliente não encontrado na base de dados
404not foundPedido não encontrado.order_code inexistente nesta conta ou que não pertence a esta API
406not acceptableInvalid Params (JSON)Estrutura JSON inválida ou malformada
409conflictPedido já vinculado a outra nota fiscal (nota_fiscal_id).O pedido já tem outra NF-e
409conflictPedido em status que não permite vínculo (status).O pedido não está em aberto, pago ou pendente
409conflictNota fiscal já cadastrada (nota_fiscal_id).A NF-e já está gravada no Frete Barato e não se une ao pedido
409conflictNota fiscal já vinculada a outro pedido (nota_fiscal_id).A gravação esbarrou numa chave que já está em uso
500internal server errorInternal errorErro interno do servidor durante o processamento

Exemplos de erro

{
  "message": "Field [request_id] is required",
  "code": 400
}

Siga as boas práticas

  • Request ID único — Sempre gere um identificador único (UUID v4 ou ULID) para cada requisição. Isso facilita rastreamento e debug.
  • Timestamp preciso — Utilize formato ISO 8601 com timezone (ex: 2025-10-29T15:12:34Z) para garantir precisão temporal.
  • Validação prévia — Valide a estrutura do XML antes de codificar em Base64 para evitar erros desnecessários.
  • Chave de acesso — Certifique-se de que a chave de 44 caracteres corresponde exatamente à chave presente no XML da NF-e.
  • Mimetype correto — Declare o mimetype correto (application/xml ou text/xml).
  • Tratamento de erros — Implemente lógica de retentativa para erros temporários (500) e tratamento adequado para erros de validação (400).
  • Logs e auditoria — Mantenha logs detalhados das requisições usando o request_id como chave de rastreamento.
  • Segurança — Nunca exponha o Bearer Token em logs ou sistemas de monitoramento.

Entenda o fluxo de processamento

Recepção

A API recebe o payload JSON com o documento em Base64.

Autenticação

Valida o Bearer Token e as credenciais do cliente.

Validação estrutural

Verifica todos os campos obrigatórios e seus formatos.

Decodificação

Decodifica o documento Base64 para o formato original.

Validação de conteúdo

Verifica se o conteúdo corresponde ao mimetype declarado.

Processamento

Executa as regras de negócio e a persistência dos dados. Com order_code, a NF-e é gravada no pedido informado.

Resposta

Retorna um JSON com o resultado do processamento.

Copyright © 2026