FreteBarato
Recursos da API

Nota Fiscal

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 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)
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

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

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
401unauthorizedAuthentication failureFalha na autenticação: token inválido ou versão incorreta da API
403forbiddenAccess deniedAcesso negado ao recurso solicitado
404not foundCustomer not foundCliente não encontrado na base de dados
406not acceptableInvalid Params (JSON)Estrutura JSON inválida ou malformada
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.

Resposta

Retorna um JSON com o resultado do processamento.

Copyright © 2026